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

LocationScope
config.toml in easy-review's app-data directoryEverything
built-inDefaults, 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"]

[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.