zereight roborev Guide
Core rule: Never run commands that modify code, commits, hooks, or roborev config without explicit user confirmation.
Intent Routing
| Intent | Action |
|---|---|
| install/setup in a repo | roborev init [--agent <name>] (confirm first) |
| inspect paths | which roborev, read hooks/config files |
| check daemon | roborev status |
| view review result | roborev show, roborev show HEAD, roborev show <sha>, roborev show --job <id> |
| list reviews | roborev list, roborev list --open, roborev list --status failed |
| configure agent/model | roborev config list, edit ~/.roborev/config.toml |
| troubleshoot | roborev status, roborev check-agents, read logs |
| run fix/refine | explain difference, confirm before executing |
Installation & Version
which roborev # /opt/homebrew/bin/roborev (typical)
roborev version # e.g. v0.55.0
- Installed via Homebrew:
/opt/homebrew/Cellar/roborev/<version>/bin/roborev - Repo-level config (per-repo):
.roborev.toml
Path Reference
| Path | Description |
|---|---|
/opt/homebrew/bin/roborev |
Binary (typical) |
~/.roborev/config.toml |
Global config |
~/.roborev/reviews.db |
SQLite review database |
~/.roborev/logs/jobs/ |
Job log files |
~/.roborev/activity.log |
Activity log |
~/.roborev/errors.log |
Error log |
~/.roborev/post-commit.log |
Post-commit hook log |
.roborev.toml |
Per-repo config (repo root) |
.git/hooks/post-commit |
Post-commit hook |
.git/hooks/post-rewrite |
Post-rewrite hook |
Inspection Commands (read-only, safe)
Daemon & Queue
roborev status # Daemon uptime, worker count, queue depth
roborev status --json # Structured output
Example output:
Daemon: running (uptime: 15m 28s) [v0.55.0]
Workers: 0/4 active
Jobs: 0 queued, 0 running, 4 completed, 0 failed, 0 skipped
Health: OK
+ database: healthy
+ workers: healthy
Review Jobs
roborev list # Jobs for current repo/branch
roborev list --open # Only open (unresolved) reviews
roborev list --status done # Filter by status (queued/running/done/failed)
roborev list --status failed # Only failed jobs
roborev list --status queued # Only queued jobs
roborev list --branch main # Filter by branch
roborev list --limit 10 # Limit results
roborev list --json # JSON output
Review Results
roborev show # Review for HEAD (latest commit)
roborev show HEAD # Same
roborev show <sha> # Review for a specific commit
roborev show <job-id> # Review by job ID (numeric)
roborev show --job <job-id> # Force as job ID
roborev show --json <job-id> # JSON output
roborev show --prompt <job-id> # Show the prompt sent to the agent
Agent Logs
roborev log <job-id> # Human-friendly rendered output
roborev log --raw <job-id> # Raw JSONL
roborev log --path <job-id> # Print log file path
roborev log clean # Remove old job log files
Wait for Completion
roborev wait # Wait for most recent HEAD job
roborev wait <sha> # Wait for a specific commit's job
roborev wait --job <id> # Wait for specific job ID
roborev wait --job 10 20 30 # Wait for multiple job IDs
Hook Inspection
ls -la .git/hooks/post-commit
ls -la .git/hooks/post-rewrite
read .git/hooks/post-commit
read .git/hooks/post-rewrite
Config Inspection
roborev config list # List all config values
roborev config get <key> # Get a specific value
read ~/.roborev/config.toml # Raw config file
read .roborev.toml # Per-repo config (if exists)
Agent & Model Configuration
Config file: ~/.roborev/config.toml
Key configuration fields:
# Default agent when no workflow-specific agent is set.
default_agent = 'codex'
default_model = ''
# Review workflow
review_agent = ''
review_model = ''
review_reasoning = '' # fast|standard|medium|thorough|maximum
# Refine workflow (iterative fix loop)
refine_agent = ''
refine_model = ''
refine_reasoning = ''
# Fix workflow (single-pass fix)
fix_agent = ''
fix_model = ''
fix_reasoning = ''
# Security review
security_agent = ''
security_model = ''
# Design review
design_agent = ''
design_model = ''
# Reasoning-level-specific agents (per-workflow granularity)
review_agent_standard = ''
review_agent_thorough = ''
review_agent_maximum = ''
refine_agent_fast = ''
refine_agent_standard = ''
# ... same pattern for fix_, security_, design_
# Model overrides per reasoning level
review_model_thorough = ''
review_model_maximum = ''
refine_model_thorough = ''
refine_model_maximum = ''
# ...
# Backup agents (fallback on primary failure)
review_backup_agent = ''
refine_backup_agent = ''
fix_backup_agent = ''
# Severity thresholds
review_min_severity = '' # critical|high|medium|low
refine_min_severity = ''
fix_min_severity = ''
# Agent CLI command overrides
codex_cmd = 'codex'
claude_code_cmd = 'claude'
pi_cmd = 'pi'
opencode_cmd = 'opencode'
cursor_cmd = 'agent'
# Codex-specific options
[agent.codex]
disable_review_skills = true # Disable Codex skill instructions for review jobs
ignore_review_user_config = true # Pass --ignore-user-config to Codex
Supported Agents
Checked automatically by roborev check-agents:
| Config name | CLI command |
|---|---|
codex |
codex |
claude-code |
claude |
gemini |
(Gemini CLI) |
copilot |
(GitHub Copilot CLI) |
opencode |
opencode |
cursor |
agent |
pi |
pi |
Reasoning Levels
Each workflow supports per-level agent and model overrides.
Levels: fast, standard (default), medium, thorough, maximum.
For roborev fix and roborev refine, pass --reasoning:
roborev fix --reasoning thorough
roborev refine --reasoning maximum
Common Configuration Patterns
Set a default agent:
roborev config set default_agent codex
Set review-specific agent:
roborev config set review_agent claude-code
Set model for thorough reviews:
roborev config set review_model_thorough claude-sonnet-4-20250514
Set agent CLI path:
roborev config set codex_cmd /path/to/codex
After config changes, restart daemon:
roborev daemon restart
Check agents are working:
roborev check-agents
Post-Commit Workflow
Normal Flow
git commit→ post-commit hook fires- Hook calls
roborev post-commit→ job enqueued - Daemon picks up job → agent reviews the diff
- Job completes → result stored in
~/.roborev/reviews.db - View result:
roborev showorroborev show HEAD
Review-Fix Loop
After seeing review findings, confirm before fixing:
roborev show # review findings
roborev list --open # open (unresolved) jobs
Two modes for addressing findings:
| Command | Behavior | Confirm? |
|---|---|---|
roborev fix |
Single-pass fix. Agent applies changes and commits. No re-review. | ✅ Yes |
roborev refine |
Iterative loop. Fix → commit → wait for re-review → repeat until pass or max iterations. Uses isolated worktree. | ✅ Yes |
refine examples:
roborev refine # Auto-fix loop on current branch
roborev refine --list # Preview without running
roborev refine --reasoning thorough # Use thorough reasoning
roborev refine --max-iterations 5 # Limit iterations
roborev refine --since <base-commit> # Starting point
roborev refine --branch main # Validate branch before refining
fix examples:
roborev fix # Fix all open jobs on current branch
roborev fix 123 # Fix a single job
roborev fix 123 124 125 # Fix multiple jobs
roborev fix --batch-size 5 # Up to 5 reviews per agent call
roborev fix --agent claude-code # Use specific agent
roborev fix --reasoning medium # Reasoning level
roborev fix --min-severity high # Only high+ severity findings
Safety Gates
Always confirm before running these commands:
| Command | Risk |
|---|---|
roborev init |
Creates hooks, config, starts daemon |
roborev install-hook |
Modifies .git/hooks/ |
roborev uninstall-hook |
Removes hooks |
roborev fix |
Modifies code and commits |
roborev refine |
Modifies code and commits (iteratively) |
roborev update |
Updates binary |
roborev daemon restart |
Restarts background service |
roborev config set |
Changes runtime behavior |
git commit |
Creates commits |
git reset |
Rewrites history |
git rebase |
Rewrites history |
Always confirm before editing these files:
| File | Purpose |
|---|---|
~/.roborev/config.toml |
Global config |
.roborev.toml |
Per-repo config |
.git/hooks/post-commit |
Post-commit hook |
.git/hooks/post-rewrite |
Post-rewrite hook |
Troubleshooting
Daemon not running
roborev status # Check daemon
roborev daemon start # Start if stopped
roborev daemon restart # Restart if needed
Post-commit hook didn't fire
ls -la .git/hooks/post-commit # Check if hook exists
read .git/hooks/post-commit # Inspect hook content
roborev install-hook --force # Reinstall if missing/broken
Job stuck in "queued"
roborev status # Check workers available
# If workers=0/4, daemon may need restart
roborev daemon restart
Agent not responding
roborev check-agents # Verify agent CLI works
roborev check-agents --agent codex # Check specific agent
roborev check-agents --timeout 30 # Per-agent timeout
Wrong model/agent being used
roborev config list # Current config
read ~/.roborev/config.toml # Verify settings
roborev daemon restart # Must restart after config change
Git index lock
# First check if a git process is still running
ps aux | grep git
# Only remove .git/index.lock after confirming no active git process
Job failed
roborev show <job-id> # Review findings and error
roborev log <job-id> # Full agent log
roborev list --status failed # All failed jobs
Per-Repo Config (.roborev.toml)
Optional. Placed in repo root. Supports:
review_guidelines— custom review rules stringexclude_patterns— globs to exclude from review diffs- Agent/model overrides scoped to the repo
Summary Commands
roborev summary # Aggregate review statistics
roborev insights # Analyze patterns in failing reviews
roborev insights --since 7d # Last 7 days
roborev insights --agent gemini # Use specific agent for analysis
TUI
roborev tui # Interactive terminal UI
TUI key features:
- Queue view with job status, branch, agent, time
- Filter by repo/branch/status
- Mouse support (configurable)
- Customizable columns