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:

Config type	Input format	Example
string	as-is	codex
integer	decimal number	8
boolean	true/false, 1/0	true
string array	comma-separated	"org/repo1,org/repo2"

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

Note

Some keys are scoped to one file. For example, server_addr is global-only and cannot be set with --local. The command will tell you if a key doesn’t belong in the scope you chose.

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 for fix and refine
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

# 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.
"""

Per-Repository Options

Option	Type	Description
agent	string	AI agent to use for this repo
model	string	Model to use (overrides global default_model)
display_name	string	Custom name shown in TUI
review_context_count	int	Number of recent reviews to include as context
excluded_branches	array	Branches to skip automatic reviews on
excluded_commit_patterns	array	Commit message substrings to skip reviews on (case-insensitive)
post_commit_review	string	Post-commit hook behavior: "commit" (default) or "branch"
review_reasoning	string	Reasoning level for reviews: thorough, standard, fast
refine_reasoning	string	Reasoning level for refine: thorough, standard, fast
fix_min_severity	string	Minimum severity for fix: critical, high, medium, or low
refine_min_severity	string	Minimum severity for refine: critical, high, medium, or low
reuse_review_session	bool	(Experimental) Resume prior agent sessions on the same branch. See Session Reuse
reuse_review_session_lookback	int	Max recent session candidates to consider (default: unlimited). See Session Reuse
review_agent_<level>	string	Agent to use for reviews at specific reasoning level
review_model_<level>	string	Model to use for reviews at specific reasoning level
refine_agent_<level>	string	Agent to use for refine at specific reasoning level
refine_model_<level>	string	Model to use for refine at specific reasoning level
fix_agent	string	Agent to use for fix / analyze —fix
fix_agent_<level>	string	Agent to use for fix at specific reasoning level
fix_model	string	Model to use for fix / analyze —fix
fix_model_<level>	string	Model to use for fix at specific reasoning level
security_agent	string	Agent to use for --type security reviews
security_agent_<level>	string	Agent for security reviews at specific reasoning level
security_model	string	Model for security reviews
security_model_<level>	string	Model for security reviews at specific reasoning level
design_agent	string	Agent to use for --type design reviews
design_agent_<level>	string	Agent for design reviews at specific reasoning level
design_model	string	Model for design reviews
design_model_<level>	string	Model for design reviews at specific reasoning level
backup_agent	string	Fallback agent if primary fails
review_backup_agent	string	Fallback agent for reviews
refine_backup_agent	string	Fallback agent for refine
fix_backup_agent	string	Fallback agent for fix
security_backup_agent	string	Fallback agent for security reviews
design_backup_agent	string	Fallback agent for design reviews
review_guidelines	string	Project-specific guidelines for the reviewer

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.

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.2-codex"

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

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

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.

Global Configuration

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

default_agent = "codex"
default_model = "gpt-5.2-codex"  # 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

Option	Type	Default	Description	Hot-Reload
default_agent	string	auto-detect	Default AI agent to use	Yes
default_backup_agent	string	-	Fallback agent when the primary fails	Yes
default_backup_model	string	-	Fallback model used when a backup agent runs	Yes
default_model	string	agent default	Model to use (format varies by agent)	Yes
server_addr	string	127.0.0.1:7373	Daemon listen address	No
max_workers	int	4	Number of parallel review workers	No
job_timeout	duration	10m	Per-job timeout	Yes
allow_unsafe_agents	bool	false	Enable agentic mode globally	Yes
anthropic_api_key	string	-	Anthropic API key for Claude Code	Yes
review_context_count	int	3	Recent reviews to include as context	Yes
reuse_review_session	bool	false	(Experimental) Resume prior agent sessions on the same branch. See Session Reuse	Yes
reuse_review_session_lookback	int	0	Max recent session candidates to consider (0 = unlimited)	Yes
hide_closed_by_default	bool	false	Start TUI with closed/failed/canceled reviews hidden	N/A
auto_filter_repo	bool	false	Auto-filter TUI to the current repo on startup	N/A
auto_filter_branch	bool	false	Auto-filter TUI to the current branch/worktree on startup	N/A
mouse_enabled	bool	true	Enable mouse interactions in the TUI (also togglable from the TUI options menu)	N/A
tab_width	int	2	Tab expansion width for code blocks in TUI (1-16)	N/A
column_borders	bool	false	Show ▕ separators between TUI columns	N/A
column_order	array		Custom queue column display order	N/A
task_column_order	array		Custom task column display order	N/A

Note

The previous config key hide_addressed_by_default is still read as a fallback. If you have it set and hide_closed_by_default is not present, the old value is used automatically. No action is required, but new configs should use the new name.

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)
└── reviews.db     # SQLite database

Override with the ROBOREV_DATA_DIR environment variable:

export ROBOREV_DATA_DIR=/custom/path

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.2"

# Anthropic models (Claude Code)
default_model = "claude-sonnet-4-5-20250929"

# OpenCode (provider/model format)
default_model = "anthropic/claude-sonnet-4-5-20250929"

Agentic Mode

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

allow_unsafe_agents = true

Caution

This makes all review operations potentially write to your codebase. Use with caution. It’s generally safer to enable agentic mode per-job with --agentic.

Advanced Section

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

~/.roborev/config.toml

[advanced]
enable_tasks = true   # Enable background tasks in the TUI

Option	Type	Default	Description
enable_tasks	bool	false	Enable the TUI background tasks workflow (fix jobs, patch application, rebasing)

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.

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

Hook Options

Option	Type	Description
event	string	Event to match: review.completed, review.failed, or review.*
command	string	Shell command with {var} template interpolation
type	string	Built-in hook type (beads, webhook), or omit for custom command
url	string	Webhook destination URL (required when type = "webhook")

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

Reasoning Levels

Reasoning levels control how deeply the AI analyzes code.

Level	Description	Best For
thorough	Deep analysis with extended thinking	Code reviews (default)
standard	Balanced analysis	Refine command (default)
fast	Quick responses	Rapid feedback

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.

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.