Core Concepts
Configuration
er is configured with TOML — there are no required CLI flags. One file holds everything: any key it
omits falls back to the built-in default. Settings apply live and save as you change them, so there is no unsaved
state to lose. The desktop app exposes most of these through a settings GUI.
Where config lives
| Location | Scope |
|---|---|
config.toml in easy-review's app-data directory | Everything |
| built-in | Defaults, used for any key the file omits |
There is one config file, shared by every repo — there is no per-repo override. On macOS it lives
at ~/Library/Application Support/easy-review/config.toml; elsewhere it is the platform app-data
directory plus easy-review. ER_CONFIG_PATH overrides the file and
ER_STORAGE_ROOT moves the whole data directory, config included.
The desktop app's projects.json and tabs.json live in the platform config
directory — ~/Library/Application Support/er/ on macOS, ~/.config/er/ on Linux — which
is a different location from the config above. A config.toml left there by an older install is
copied into the managed location once, on first run, and then left alone: editing it afterwards does nothing.
That legacy file is the only thing you will find in ~/.config/er/ on macOS.
Live editing terminal
Press , inside er to open the settings hub. Changes apply immediately so you can see
the effect, and each one is written to the global config as you make it — there is nothing to save.
s or Esc closes the hub.
Settings GUI desktop
The desktop app has a dedicated settings page (command palette → Open settings) covering the same options in three scopes: General — the options shared with the terminal (theme, AI Hub providers and models, concurrency, commands, watched paths); Terminal — the TUI's own view modes, display and key hints; and Projects — per-project review settings. Changes apply live and are written back to the same global config file, so the two apps always agree.
[features] — which modes and features are on
Feature toggles. All default to true.
[features]
view_branch = true # Branch diff
view_unstaged = true # Unstaged changes
view_staged = true # Staged changes
view_history = true # Commit history
view_conflicts = true # Merge conflicts (tab appears during a merge)
view_hidden = true # Hidden / watched files (tab appears when [watched] paths exist)
view_tour = true # Guided Tour walkthrough (tab appears when a tour.json exists)
arena = true # Multi-reviewer arena (desktop)
Disabling a view mode removes its tab and renumbers the rest — there are no gaps in the number keys.
[display] — rendering
[display]
theme = "graphite" # graphite (default) | slate | midnight | ember | paper | daylight | contrast-dark | contrast-light
line_numbers = true
wrap_lines = false # wrap long lines instead of scrolling horizontally
split_diff = false # side-by-side diff view
tab_width = 4 # spaces per tab (1–16)
auto_context_threshold = 100 # auto-expand context for small files, tiered by diff size (0 disables)
The theme drives both the terminal and desktop UIs: four dark themes (Graphite, the default, plus Slate, Midnight, Ember), two light (Paper, Daylight), and two AAA high-contrast variants (Contrast Dark, Contrast Light). Each maps to a matching syntax-highlighting theme. Older theme names (ocean-depth, moonlight, daybreak, high-contrast, …) still resolve via aliases.
[hints] — bottom-bar key hints terminal
[hints]
navigation = true # j/k, n/N, Space, /
comments = true # q, c, r, x
staging = true # s, commit
verbose = false # show all keybindings
[agent] and [ai_hub] — AI providers
[agent] is the single-command fallback — the executable and args used when no [ai_hub]
provider resolves. {prompt} is replaced with the generated prompt.
[agent]
command = "claude"
args = ["--print", "--output-format", "stream-json", "-p", "{prompt}"]
The optional [ai_hub] block defines presets — multiple providers and their models —
so you can switch at runtime without editing config. Provider args are the shared base; each model's
args are appended after them (OpenCode inserts model/effort flags before {prompt}).
[ai_hub]
default_provider = "claude"
default_model = "sonnet-5.5"
default_effort = "medium" # reasoning effort passed to providers that support it
max_concurrent_reviews = 3 # queue further reviews beyond this many at once (1–16)
[ai_hub.providers.claude]
label = "Claude"
command = "claude"
args = ["--print", "-p", "{prompt}"]
[[ai_hub.providers.claude.models]]
id = "sonnet-5.5"
label = "Sonnet 5.5"
args = ["--model", "claude-sonnet-5-5"]
effort_levels = ["low", "medium", "high", "xhigh", "max"]
# empty effort_levels means Auto only; support comes from metadata, not model IDs
[ai_hub.providers.opencode]
label = "OpenCode"
command = "opencode"
args = ["run", "--auto", "{prompt}"]
[[ai_hub.providers.opencode.models]]
id = "default"
label = "Default"
args = []
effort_levels = ["low", "medium", "high", "xhigh", "max"]
- If
[ai_hub]is absent,erseeds it from the built-in catalog on load, so the presets above exist out of the box. The single[agent]config is used only when no provider resolves at all. - Selection can be changed at runtime and saved globally from Desktop Settings or the TUI General settings.
- On load,
ermerges any missing built-in catalog models into your config in memory — it does not rewrite your file. - Each release ships a preset list per provider. Refresh models adds what the provider CLI itself lists, for Codex, Cursor and OpenCode. The Claude CLI has no listing, so Claude offers the presets of the release you run. A preset dropped from the catalog is dropped from the loaded config too, and a default that pointed at it moves to its successor.
- The selected default provider/model applies to every ordinary AI Hub action, including review, triage, tours, experts, Professor, validation, questions, summary, and card AI. Explicit review-run selections apply only to that run.
- Built-in Claude, Codex, Cursor Agent, and OpenCode launches can read and write managed review storage. On macOS this is
~/Library/Application Support/easy-review/; OpenCode uses--autoplus anOPENCODE_PERMISSIONobject that denies other external paths and allows only the active review bucket. Card AI keeps--autowith a read-only permission object. Custom provider commands are left unchanged.
[summary] — diff summaries
[summary]
push_to_pr = false # auto-push the generated summary to the GitHub PR body
The summary is generated by whichever agent runs your AI Hub actions (see [agent] and
[ai_hub] above); push_to_pr is the only key this section reads.
[watched] — monitor git-ignored files
Glob patterns for ignored paths to watch — for example, an AI assistant's sync folder. Watched files appear in the file tree alongside tracked changes; toggle the section with W.
[watched]
paths = [".work/**/*", ".er/**/*"] # patterns matched against the repo root
diff_mode = "content" # "content" (show file) or "snapshot" (diff vs saved baseline)
Watched files should be in .gitignore. er runs a safety check and warns if a
watched pattern is not actually ignored.
[commands] — hub shell actions
Optional shell commands for hub actions, run via sh -c. Leave one unset and its hub row stays
listed but disabled. Placeholders: {base}, {branch}, {repo},
{output}.
[commands]
# summary = "claude --print -p 'Summarize this diff: {base}...{branch}'"
# test = "cargo test"
# lint = "cargo clippy"
# typecheck = "cargo check"
# security = "cargo audit"
In a mono-repo, an optional [packages] section defines the same commands per package — each key
(e.g. [packages.api]) takes its own label, test, lint,
typecheck, and security commands, and the Verify hub groups them by package.
Worked example
The single config file, with every key you leave out falling back to its default:
[features]
view_conflicts = false
[display]
tab_width = 2
wrap_lines = true
[watched]
paths = [".work/**/*", ".er/**/*", "logs/**/*.log"]
diff_mode = "snapshot"
Watched paths are the one setting that is repo-specific in effect: the globs are global, but each only matches inside the repo you are reviewing. If you need different watched paths per project, that is the reason — there is no per-repo file to put them in.