Configuration

roborev uses a layered configuration system. Settings are resolved in this order (highest to lowest priority):

1. CLI flags (--agent, --model, --reasoning)
2. Per-repo .roborev.toml in your repository root
3. Global ~/.roborev/config.toml
4. Defaults (auto-detect agent, thorough reasoning for reviews)

The config Command¶

The roborev config command lets you inspect and modify configuration from the command line, similar to git config. It works with both global and per-repo config files.

Get a value¶

roborev config get default_agent              # merged: tries local, then global
roborev config get default_agent --global     # global config only
roborev config get review_agent --local       # repo config only
roborev config get sync.enabled               # nested keys use dot notation

Without --global or --local, get uses merged scope: it checks the repo config first, then falls back to global. The raw value is printed to stdout for easy piping.

Set a value¶

roborev config set default_agent codex --global
roborev config set max_workers 8 --global
roborev config set review_agent claude-code    # defaults to --local
roborev config set sync.enabled true --global
roborev config set ci.repos "org/repo1,org/repo2" --global

Without --global or --local, set defaults to writing the repo config (.roborev.toml). You must be inside a git repository for local writes.

Values are automatically coerced to the correct type:

Writes are atomic (temp file + rename) and preserve file permissions: 0600 for global config (which may contain secrets) and 0644 for repo config.

List all values¶

roborev config list                    # merged config (effective values)
roborev config list --global           # global config only
roborev config list --local            # repo config only
roborev config list --show-origin      # show where each value comes from

The --show-origin flag adds a column showing whether each value comes from global, local, or default:

global  default_agent   codex
local   review_agent    claude-code
default max_workers     4

Sensitive values (API keys, database URLs) are automatically masked in list output, showing only the last 4 characters.

Per-Repository Configuration¶

Create .roborev.toml in your repository root to customize behavior for that project.

agent = "gemini"                  # AI agent to use
model = "gemini-3-flash-preview"  # Model override for this repo
review_context_count = 5   # Recent reviews to include as context
display_name = "backend"   # Custom name shown in TUI (optional)
excluded_branches = ["wip", "scratch"]  # Branches to skip reviews on

# Reasoning levels: thorough, standard, fast
review_reasoning = "thorough"  # For code reviews (default: thorough)
refine_reasoning = "standard"  # For refine command (default: standard)

# Severity filtering
review_min_severity = "medium"  # Skip low-severity findings in reviews
fix_min_severity = "medium"     # Skip low-severity findings in fix
refine_min_severity = "medium"  # Skip low-severity findings in refine

# Session reuse (experimental)
reuse_review_session = true     # Resume prior agent sessions on same branch

# Auto-close passing reviews
auto_close_passing_reviews = true

# Project-specific review guidelines
review_guidelines = """
No database migrations needed - no production databases yet.
Prefer composition over inheritance.
All public APIs must have documentation comments.
"""

[kata_context]
mode = "current"   # off (default), current, or open
max_chars = 50000

Per-Repository Options¶

Review Guidelines¶

Use review_guidelines to give the AI reviewer project-specific context: suppress irrelevant warnings, enforce conventions, or describe trust boundaries and architecture so the reviewer doesn't flag non-issues:

review_guidelines = """
This is a local CLI tool. The daemon runs on localhost and all
displayed data originates from the user's own filesystem and git
repos. Do not flag injection or sanitization for data that never
crosses a trust boundary.

Performance is critical - flag any O(n^2) or worse algorithms.
All error messages must be user-friendly.
"""

Guidelines are included in the review prompt, so they shape what the reviewer flags and what it ignores. Common uses:

• Trust boundaries: Describe where untrusted data enters the system so the reviewer doesn't flag sanitization for trusted paths.
• Architecture constraints: Note that the daemon and client evolve in lockstep, that backward compatibility isn't required, etc.
• Suppress noise: Tell the reviewer to skip narrow-terminal overflow, localhost rate-limiting, or other non-issues for your project.

Kata Integration¶

If your repo is bound to a Kata project with a committed .kata.toml, roborev can include Kata task context in review prompts. For an overview of both directions of the integration, see Kata.

# .roborev.toml or ~/.roborev/config.toml
[kata_context]
mode = "current"   # off (default), current, or open
max_chars = 50000  # cap on Kata context bytes in the prompt

current mode frames referenced issues as authoritative task intent. open mode frames the open backlog as background context so the reviewer does not treat every open issue as part of the current change. Dirty reviews have no commit messages to inspect, so current mode includes no Kata context for them; use open if you want dirty reviews to see the backlog.

Kata context applies to local review prompts only (single commit, branch ranges, and dirty reviews). Daemon CI pull-request reviews never include Kata context, since PR head content is untrusted and backlog details could leak into public PR comments. Fix and task jobs do not receive Kata context either.

The kata CLI must be on PATH. If the CLI is missing or the repo is not bound to Kata, roborev skips the context without failing the review. If a binding exists but is broken, or a referenced issue cannot be loaded, the daemon logs the error and includes a note in the prompt when useful.

Kata context is optional prompt context. If the prompt exceeds max_prompt_size, roborev trims other optional context first and drops Kata context last.

To file failed reviews and review findings back into Kata, configure a type = "kata" review hook. See Built-in: Kata Integration.

Workflow-Specific Agent and Model¶

Use different agents or models depending on the workflow and reasoning level:

# Use a faster model for quick reviews, thorough model for deep analysis
review_model = "claude"
review_model_fast = "claude-sonnet-4-5-20250929"
review_model_thorough = "claude-opus-4-5-20251101"

# Use different agents and models for refine
refine_agent_fast = "gemini"
refine_model_fast = "gemini-3-flash"
refine_agent_thorough = "codex"
refine_model_thorough = "gpt-5.5"

Base keys use the pattern {workflow}_agent and {workflow}_model (e.g. review_model, refine_agent, fix_agent, security_agent, design_model) to set the default for each workflow. Level-specific keys override for a given reasoning level: - {workflow}_model_{level} or {workflow}_agent_{level} - workflow is review, refine, fix, security, or design - level is thorough, standard, or fast

The fallback hierarchy for each workflow is: - CLI flag > repo {workflow}_agent_{level} > repo {workflow}_agent > repo agent > global {workflow}_agent_{level} > global {workflow}_agent > global default_agent > codex

Review Panels¶

Use [review] to configure subagent review panels. A panel fans one daemon review target out to named reviewers and stores one synthesis parent review:

[review]
default_panel = "branch_final"
hook_review_panel = "quick"

[review.subagents.bug]
agent = "codex"
review_type = "default"
instructions = "Focus on correctness, regressions, and missing tests."

[review.subagents.security]
agent = "claude-code"
review_type = "security"

[review.panels.branch_final]
members = ["bug", "security"]
synthesis_agent = "codex"

default_panel applies to manual daemon reviews when --panel is not set. hook_review_panel applies to automatic post-commit reviews. CI reviews can select a named panel with [ci] panel = "branch_final".

Global and repo panel maps are merged by name, with repo entries overriding global entries. See Subagent Review Panels for the full reference.

Backup Agents¶

If the primary agent fails (rate limits, network errors, crashes), roborev can automatically retry the job with a backup agent. This is useful when your primary agent has usage caps. For example, Codex plans often hit rate limits during heavy review sessions, so falling back to Claude Code keeps reviews flowing.

# ~/.roborev/config.toml
default_agent = "codex"
default_backup_agent = "claude-code"  # Fallback for any workflow
default_backup_model = "claude-sonnet-4-20250514"  # Model for the backup agent

When a backup agent takes over, it uses the model specified by default_backup_model. Without this setting, the backup agent uses whatever model is configured for it normally. This is useful when your backup agent needs a different model than the one configured as default_model (which is typically chosen for the primary agent).

You can also set backup agents per workflow:

# ~/.roborev/config.toml
review_backup_agent = "claude-code"   # Fallback for reviews
refine_backup_agent = "codex"         # Fallback for refine
fix_backup_agent = "claude-code"      # Fallback for fix

Per-repo overrides work the same way in .roborev.toml:

# .roborev.toml
backup_agent = "claude-code"          # Repo-level fallback
review_backup_agent = "gemini"        # Workflow-specific override

When a job fails with an agent error (not a review finding), roborev resolves the backup agent in this order:

1. Repo-level workflow-specific backup (e.g. review_backup_agent in .roborev.toml)
2. Repo-level generic backup_agent
3. Global workflow-specific backup (e.g. review_backup_agent in config.toml)
4. Global default_backup_agent

If a backup agent is found and installed, the job is retried with that agent. The failover is logged in the daemon output. If no backup is configured or the backup agent isn't installed, the job fails normally.

Agent Command Overrides¶

If an agent binary is installed under a non-standard name or path, use a *_cmd setting to tell roborev where to find it:

# ~/.roborev/config.toml
claude_code_cmd = "/opt/bin/claude"
codex_cmd = "codex-nightly"
cursor_cmd = "/usr/local/bin/agent"
opencode_cmd = "/usr/local/bin/opencode-wrapper"
pi_cmd = "~/bin/pi"

These overrides affect both agent execution and availability detection. Without them, roborev only checks for the default command name when deciding whether an agent is installed.

Agent Name Validation¶

Unknown agent names in configuration files and CLI flags are now validated and rejected early. If you specify an agent name that roborev doesn't recognize, you'll get a clear error message at startup or command invocation instead of a confusing failure later.

Excluded Branches¶

Skip automatic reviews on work-in-progress branches:

excluded_branches = ["wip", "scratch", "experiment"]

Reviews triggered manually with roborev review still work on these branches.

Excluded Commit Patterns¶

Skip reviews for commits whose messages contain specific substrings (case-insensitive matching):

excluded_commit_patterns = ["[skip review]", "wip:", "fixup!"]

When reviewing a range, the range is skipped only if every commit in the range matches. Manually triggered reviews with roborev review are not affected.

Exclude Patterns¶

Common lockfiles and generated files are excluded from review diffs by default: package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, bun.lock, uv.lock, poetry.lock, Pipfile.lock, pdm.lock, go.sum, Cargo.lock, Gemfile.lock, composer.lock, packages.lock.json, pubspec.lock, mix.lock, Package.resolved, Podfile.lock, flake.lock, and the .beads/, .gocache/, and .cache/ directories.

To exclude additional files, use exclude_patterns in either global or per-repo config:

# .roborev.toml
exclude_patterns = ["generated.go", "*.pb.go", "vendor/"]

# ~/.roborev/config.toml
exclude_patterns = ["*.min.js", "dist/"]

Patterns can be filenames, directory names (with trailing /), or glob patterns (including **). Both global and repo-level patterns are merged. User patterns are appended to the built-in exclusion list.

Prompt Size Budget¶

The max_prompt_size (per repo) and default_max_prompt_size (global) settings control the maximum size in bytes of the prompt sent to review agents. The per-repo value takes precedence over the global default. The default is 200,000 bytes (~200 KB).

# ~/.roborev/config.toml
default_max_prompt_size = 300000   # 300 KB global default

# .roborev.toml
max_prompt_size = 500000           # 500 KB for this repo only

This limit applies to all review commands (review, compact, ci review) and all agents. When a diff exceeds the budget, roborev writes the full diff to an external snapshot file in a per-snapshot directory and includes fallback instructions in the prompt pointing the agent at the snapshot path. Codex receives the snapshot directory via --add-dir. Optional context (prior reviews, guidelines) is trimmed first to preserve as much inline diff as possible. Final prompt size is checked before submission, and context-window failures fail or fail over rather than retrying the same oversized prompt.

By default, snapshots are written to .roborev/ under the repo root so the agent sandbox does not need broader filesystem access. Override the location with snapshot_dir in .roborev.toml:

# .roborev.toml
snapshot_dir = ".cache/roborev"

snapshot_dir must be a relative path under the repo root, must not be inside .git, and must not contain control characters. roborev init ensures the configured directory is ignored in .gitignore; snapshot creation also writes a local .git/info/exclude fallback for existing checkouts whose ignore setup is stale.

Post-Commit Review Mode¶

By default, the post-commit hook reviews the single commit at HEAD. Set post_commit_review = "branch" to review all commits since the branch diverged from the base branch instead:

post_commit_review = "branch"

When set to "branch", each commit triggers a merge-base..HEAD range review covering the entire branch. On the base branch itself (e.g. main), detached HEAD, or any error, the hook falls back to a single-commit review.

This setting only affects the post-commit hook. roborev review is not changed by this option.

Auto-Close Passing Reviews¶

By default, all reviews remain open in the queue until you explicitly close them. Set auto_close_passing_reviews = true to automatically close reviews that pass with no findings:

auto_close_passing_reviews = true

When enabled, reviews with a passing verdict are closed immediately after the verdict is parsed. Failed reviews remain open for attention. This is useful if you only want to focus on reviews that found issues.

The option works in both global config (~/.roborev/config.toml) and per-repo config (.roborev.toml). Per-repo settings override the global value.

Global Configuration¶

Create ~/.roborev/config.toml to set system-wide defaults.

default_agent = "codex"
default_model = "gpt-5.5"  # Default LLM
default_backup_model = "claude-sonnet-4-20250514"  # Fallback model for backup agent
server_addr = "127.0.0.1:7373"
max_workers = 4
job_timeout = "10m"  # Per-job timeout (default: 10m)
hide_closed_by_default = true     # Start TUI with closed/failed/canceled hidden
auto_filter_repo = true           # Auto-filter TUI to current repo on startup
auto_filter_branch = true         # Auto-filter TUI to current branch/worktree on startup
mouse_enabled = true              # Enable mouse interactions in the TUI
tab_width = 4                     # Tab expansion width for code blocks in TUI (default: 2)
column_borders = true             # Show separators between TUI columns

Global Options¶

Hot-Reload¶

The daemon automatically watches ~/.roborev/config.toml for changes. Most settings take effect immediately without restarting the daemon.

Settings that require daemon restart: server_addr, max_workers, the [ci] section, and the [sync] section.

Data Directory¶

All roborev data is stored in ~/.roborev/ by default:

~/.roborev/
├── config.toml       # Global configuration
├── daemon.json       # Runtime state (port, PID)
├── post-commit.log   # JSONL log of post-commit hook invocations
├── reviews.db        # SQLite database
└── logs/jobs/        # Persistent job output logs

Override with the ROBOREV_DATA_DIR environment variable:

export ROBOREV_DATA_DIR=/custom/path

Unix Domain Socket¶

On Unix systems, the daemon can listen on a Unix domain socket instead of TCP loopback. This provides filesystem-level access control: the socket is created with 0600 permissions and its parent directory with 0700, so only the owning user can connect.

To enable Unix domain sockets, set server_addr to unix://:

# ~/.roborev/config.toml
server_addr = "unix://"

With unix:// (no path), the socket is created at $XDG_RUNTIME_DIR/roborev/daemon.sock when $XDG_RUNTIME_DIR is set and points to an existing absolute directory. Otherwise, the socket is placed under the platform temp directory (e.g. /tmp on Linux, /var/folders/.../T on macOS) at {tempdir}/roborev-{UID}/daemon.sock, where {UID} is your numeric user ID. To use a specific path:

server_addr = "unix:///var/run/roborev/daemon.sock"

The CLI flag works the same way:

roborev --server unix:// tui
roborev daemon run --addr "unix:///custom/path.sock"

Stale socket files from previous daemon runs are cleaned up automatically on startup. The socket is removed on graceful shutdown.

Persistent Daemon¶

The daemon starts automatically when you run roborev init or any command that needs it, and stays running in the background. This is sufficient for most users. If you want the daemon to survive reboots, restart on failure, or be managed alongside other system services, set up a system service.

macOS (launchd):

# Resolve paths. Homebrew prefix differs between Intel and Apple Silicon
ROBOREV_BIN="$(command -v roborev)"
BREW_PREFIX="$(brew --prefix 2>/dev/null || echo /usr/local)"

mkdir -p ~/Library/Logs/roborev
cat > ~/Library/LaunchAgents/com.roborev.daemon.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.roborev.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>${ROBOREV_BIN}</string>
        <string>daemon</string>
        <string>run</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>${BREW_PREFIX}/bin:${BREW_PREFIX}/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>${HOME}/Library/Logs/roborev/daemon.log</string>
    <key>StandardErrorPath</key>
    <string>${HOME}/Library/Logs/roborev/daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.roborev.daemon.plist

The heredoc expands ${ROBOREV_BIN}, ${BREW_PREFIX}, and ${HOME} at generation time so the plist contains absolute paths. Launchd does not expand ~ or environment variables in plist values.

Linux (systemd):

roborev ships with roborev.service and roborev.socket unit files in its packaging/systemd/ directory. If your package manager installed the unit files, enable the user-level service:

systemctl --user enable --now roborev

For on-demand startup via socket activation, enable the socket unit instead. The daemon starts automatically when a client connects and uses Type=notify to signal readiness back to systemd:

systemctl --user enable --now roborev.socket

If the unit files are not available (e.g., you used go install or the install script), create a service unit manually. This covers the always-on service mode; socket activation requires the bundled unit files.

# Resolve the actual binary path for ExecStart
ROBOREV_BIN="$(command -v roborev)"

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/roborev.service << EOF
[Unit]
Description=roborev daemon
After=network.target

[Service]
ExecStart=${ROBOREV_BIN} daemon run
Restart=on-failure

[Install]
WantedBy=default.target
EOF

systemctl --user enable --now roborev

Environment Variables¶

Telemetry¶

roborev sends limited anonymous telemetry when the daemon starts and once every 24 hours while it remains running. Events are daemon_started and daemon_active, with repo count, review count, whether sync is enabled, whether CI is enabled, whether auto design review is enabled, roborev version, OS, architecture, and an anonymous install ID stored in the local database.

Telemetry does not include repo names, paths, remotes, prompts, review output, provider tokens, usernames, or IP geolocation. Disable it with either environment variable:

ROBOREV_TELEMETRY_ENABLED=0 roborev daemon run
TELEMETRY_ENABLED=0 roborev daemon run

Telemetry is disabled in Go test processes.

Color Mode¶

The TUI automatically adapts to light and dark terminals by default. Use ROBOREV_COLOR_MODE to override the auto-detection:

ROBOREV_COLOR_MODE=dark roborev tui

NO_COLOR takes precedence over ROBOREV_COLOR_MODE at all layers. When NO_COLOR is set, all ANSI color sequences are stripped regardless of ROBOREV_COLOR_MODE.

Model Selection¶

The default_model setting specifies which model agents should use. The format varies by agent:

# OpenAI models (Codex, Copilot)
default_model = "gpt-5.5"

# Anthropic models (Claude Code)
default_model = "claude-opus-4-8"

# OpenCode (provider/model format)
default_model = "anthropic/claude-opus-4-8"

Cost Usage Endpoint¶

By default, roborev looks up token usage and cost estimates through the local agentsview CLI. You can route lookup through an HTTP endpoint instead:

[cost]
endpoint = "https://usage.example.test/api/v1/sessions/{session_id}/usage"
timeout = "2s"

endpoint must include {session_id}, which roborev URL-escapes and replaces with the agent session ID. If endpoint is empty, roborev uses the agentsview CLI path. timeout defaults to 10s; invalid, zero, or negative values also fall back to 10s.

The endpoint should return JSON compatible with agentsview session usage --format json:

{
  "session_id": "session-123",
  "agent": "codex",
  "project": "myrepo",
  "total_output_tokens": 28800,
  "peak_context_tokens": 118000,
  "has_token_data": true,
  "cost_usd": 0.42,
  "has_cost": true
}

has_token_data and has_cost are required booleans. When has_token_data is true, token counts are required. When has_cost is true, cost_usd is required. A 404 response is treated as no usage data for that session.

Agentic Mode¶

Enable agentic mode globally (allows agents to edit files and run commands):

allow_unsafe_agents = true

Advanced Section¶

The [advanced] section controls opt-in features that are not part of the default workflow.

# ~/.roborev/config.toml
[advanced]
tasks_enabled = true   # Enable background tasks in the TUI

When enabled, the TUI exposes the F (fix) and T (tasks) shortcuts for launching fix jobs and managing patches. See Background Tasks for the full reference.

Codex Review Options¶

The [agent.codex] section controls Codex-specific behavior for review jobs. Both options default to true so Codex reviews start from a clean state without skill instructions or user-level Codex config. Fix jobs are not affected.

# ~/.roborev/config.toml
[agent.codex]
disable_review_skills = true       # Suppress Codex skill instructions on review jobs
ignore_review_user_config = true   # Pass --ignore-user-config to Codex review jobs

Set either to false to restore the prior behavior if you rely on Codex skill instructions or user-level Codex config during reviews.

Pi Classifier Options¶

Pi can be used as the auto design-review classifier because roborev runs Pi with a JSON schema output extension. The default extension source is npm:@nqbao/pi-json-schema@0.1.1.

Override the extension source under [agent.pi] if you vendor or mirror the extension:

[agent.pi]
jsonschemaextension = "/opt/roborev/pi-json-schema/index.ts"

Install the default extension in Pi so classifier setup is visible to pi list and so locked-down environments do not need to fetch it at runtime:

pi install npm:@nqbao/pi-json-schema

Hooks¶

Run shell commands when reviews complete or fail. See the Review Hooks guide for full details.

# In config.toml or .roborev.toml
[[hooks]]
event = "review.failed"          # or "review.completed", "review.*"
command = "notify-send 'Review failed for {repo_name}'"

[[hooks]]
event = "review.failed"
type = "beads"   # Built-in: creates a bd issue automatically

[[hooks]]
event = "review.*"
branches = ["main", "release/*"]
type = "kata"    # Built-in: creates Kata issues for failures/findings

Hook Options¶

Template variables: {job_id}, {repo}, {repo_name}, {sha}, {agent}, {verdict}, {findings}, {error}

Auto Design Review¶

Off by default. When enabled, roborev decides per commit whether to dispatch a --type design review on top of the normal code review. The router uses cheap heuristics first (path globs, diff size, file count, commit-subject regexes) and falls back to a JSON-schema-constrained classifier for ambiguous cases. The post-commit, roborev review, range, and dirty paths all consult the router, as does the CI poller when design is not already in the configured panel or review matrix. When the router decides not to run, a skipped row is recorded with a short reason and rendered dimmed in the TUI; PR synthesis includes a one-line Auto-design-review skipped: <reason> section.

By default, the TUI queue hides the auto-design-router's classifier jobs (job_type = classify) and skipped design rows (status = skipped, scoped to source = auto_design) so per-commit routing decisions do not crowd out review rows. Decisions are still recorded and counted on the daemon status endpoint. Press s in the TUI to toggle visibility for the current session, or set show_classify_jobs = true in ~/.roborev/config.toml to make them visible globally; per-repo .roborev.toml can override with a nullable show_classify_jobs field (omit to inherit). When viewing a hidden classifier or skipped row, press l to see the classifier verdict and skip_reason rendered above the (typically empty) log.

Enabling¶

Turn it on globally in ~/.roborev/config.toml:

[auto_design_review]
enabled = true

A per-repo [auto_design_review] block in .roborev.toml overrides the global value. The per-repo enabled field is tri-state: omitting it inherits the global setting, enabled = false explicitly opts a repo out of a globally-enabled default, and enabled = true opts a repo in when the global default is off.

# .roborev.toml
[auto_design_review]
enabled = false   # opt this repo out of a globally-enabled router

Heuristics¶

The router checks rules in fixed order: trigger paths, large diff, large file count, trigger message, then skip rules (trivial diff, all-files-skip, skip message). The first match wins; ambiguous commits go to the classifier.

Default trigger_paths:

**/migrations/**
**/schema/**
**/*.sql
docs/superpowers/specs/**
docs/design/**
docs/plans/**
**/*-design.md
**/*-plan.md

Default skip_paths:

**/*.md
**/*_test.go
**/*.spec.*
**/testdata/**

Default trigger_message_patterns:

\b(refactor|redesign|rewrite|architect|breaking)\b

Default skip_message_patterns:

^(docs|test|style|chore)(\(.+\))?:

List fields replace defaults wholesale. Setting an empty list (e.g. trigger_paths = []) disables that family of heuristics for the repo. Unset list fields inherit the next layer's value.

Invalid globs and uncompilable regexes fail validation at startup so config typos surface loudly instead of silently suppressing every dispatch.

Classifier¶

When heuristics are inconclusive, the router enqueues a classify job that runs the configured classifier agent against an embedded JSON schema. The agent returns a yes/no decision plus a short reason, and the router promotes the row to a design-review job or marks it skipped accordingly.

Currently claude-code (via --json-schema) and pi (via the configured JSON schema extension) implement the structured-output capability. Other agents are rejected at config-resolve time with a list of valid choices.

These keys live at the top level of the config file (not inside [auto_design_review]), since they describe the classifier agent the same way review_agent and fix_agent describe their workflows:

# ~/.roborev/config.toml
classify_agent = "claude-code"
classify_model = "claude-opus-4-8"
classify_reasoning = "fast"

[auto_design_review]
enabled = true

CI integration¶

When the CI poller picks up a PR, it runs the auto design-review router on the head SHA when design is not already in the configured panel or review matrix. If heuristic inputs (diff, changed files, commit message) fail to assemble, the commit degrades to the classifier instead of being silently skipped.

The daemon /api/status endpoint exposes a SkippedJobs aggregate count, plus an auto_design subobject with five per-outcome counters (triggered, skipped_heuristic, triggered_classifier, skipped_classifier, errored) when the feature is enabled anywhere. The subobject is omitted from the JSON when the feature is disabled across all repos.

Reasoning Levels¶

Reasoning levels control how deeply the AI analyzes code.

maximum is accepted as max or xhigh on the command line. For agents without an xhigh equivalent (Droid, Kilo, Pi), it maps to their highest available level (same as thorough).

Set per-command with --reasoning, or per-repo in .roborev.toml:

roborev review --reasoning fast      # Quick review
roborev refine --reasoning thorough  # Careful fixes

Authentication¶

Claude Code¶

Claude Code uses your Claude subscription by default. roborev deliberately ignores ANTHROPIC_API_KEY from the environment to avoid unexpected API charges.

To use Anthropic API credits instead of your subscription:

# ~/.roborev/config.toml
anthropic_api_key = "sk-ant-..."

roborev automatically sets CLAUDE_NO_SOUND=1 when running Claude agents to suppress notification and completion sounds.

To route Claude Code through a local or remote proxy (Ollama, LiteLLM, LM Studio, etc.) instead of Anthropic's API, use the <model>@<base_url> model spec. See Routing Claude Code to a Proxy.

Other Agents¶

• Codex: Uses authentication from codex auth
• Gemini: Uses authentication from Gemini CLI
• Copilot: Uses GitHub Copilot subscription via GitHub CLI
• OpenCode: Uses API keys configured in its own settings, set model to use in config TOML files

Environment Variable Expansion¶

Sensitive values can reference environment variables:

# ~/.roborev/config.toml
anthropic_api_key = "${ANTHROPIC_API_KEY}"

This keeps secrets out of config files while still allowing roborev to use them.