Reviewing Code

Feature Branches

Use --branch to review all commits since your branch diverged from main:

roborev review --branch              # Review branch vs auto-detected main/master
roborev review --branch=feature-xyz  # Review a specific branch by name
roborev review --branch --base dev   # Review branch vs specific base

Reviews are enqueued and run in the background. Open roborev tui to browse results as they complete. This is the recommended workflow for pre-merge reviews of entire feature branches.

Reviewing a Different Branch

By default --branch reviews the current branch. You can specify a branch name to review a different branch without switching to it:

roborev review --branch=feature-xyz
roborev review --branch=feature-xyz --base develop

Note: use --branch=name (with =), not --branch name. The space-separated form treats name as a positional commit argument.

How It Works

1. roborev detects the merge-base between the target branch and the base branch
2. All commits from the merge-base to the branch tip are queued for review
3. Each commit is reviewed individually by the AI agent
4. Results are stored and can be viewed in the TUI

Pre-Merge Review

Before creating a pull request, review your entire branch:

git checkout feature-branch
roborev review --branch          # Enqueue branch review (runs in background)
roborev tui                      # Browse results as they arrive
roborev compact                  # Consolidate findings across commits
roborev fix                      # Address consolidated findings

The TUI gives you a persistent queue of open reviews that must be explicitly addressed and closed, creating an accountability loop that prevents findings from getting lost.

CI Integration

if ! roborev review --branch --wait --quiet; then
    echo "Reviews found issues"
    exit 1
fi

Branch Review Options

Flag	Description
--branch [name]	Review all commits on the branch since base. Optionally specify a branch name with --branch=name.
--base <branch>	Compare against a specific base branch (default: auto-detect main/master)
--wait	Block until all reviews complete (for CI and scripting; see When to use --wait)
--quiet	Suppress output
--agent <name>	Use specific agent
--reasoning <level>	Set reasoning depth

Uncommitted Changes

Use --dirty to review working tree changes before committing:

roborev review --dirty           # Queue review of uncommitted changes

Results appear in roborev tui once the review completes.

What Gets Reviewed

The --dirty flag includes:

• Staged changes
• Unstaged changes to tracked files
• Untracked files

Dirty Review Options

Flag	Description
--wait	Block until review completes (for CI and scripting; see When to use --wait)
--quiet	Suppress output
--agent <name>	Use specific agent
--reasoning <level>	Set reasoning depth

Review Types

Use --type to change what the reviewer focuses on. Omitting --type gives you the standard code review.

roborev review                       # Default code review
roborev review --type security       # Security-focused review
roborev review --type design         # Design-focused review
roborev review --branch --type security  # Security review of branch

Type	Focus
(default)	Bugs, security, testing gaps, regressions, code quality. This is what you get when you omit --type.
security	Injection, auth, credential exposure, path traversal, unsafe patterns
design	Completeness, feasibility, task scoping, missing considerations

Review types work with all review modes (--branch, --dirty, --since, single commits, ranges).

Each type can have its own agent and model configuration via {type}_agent and {type}_model in .roborev.toml or global config. See Workflow-Specific Agent and Model.

Specific Commit Ranges

Use --since to review commits since a specific point:

roborev review --since HEAD~5       # Review last 5 commits
roborev review --since abc123       # Review commits since abc123 (exclusive)
roborev review --since v1.0.0       # Review commits since a tag

The range is exclusive of the starting commit (like git’s .. range syntax). Unlike --branch, this works on any branch including main.

Large Diffs

For --dirty reviews, diffs are limited to 200KB since uncommitted changes cannot be easily inspected by the agent. If your dirty diff exceeds this limit, commit your changes in smaller chunks.

For committed changes, diffs over 250KB are omitted from the prompt - the agent is given only the commit hash and can inspect changes using git show.

Session Reuse

Experimental

Session reuse is experimental. The behavior and configuration may change in future releases. Enable it on a per-repo basis first to evaluate before rolling out globally.

When reviewing a branch with multiple commits, each review normally starts a fresh agent session. This means the agent re-reads the repository context, re-analyzes unchanged files, and rebuilds its understanding from scratch for every commit. Session reuse changes this: when enabled, the daemon looks for a completed review on the same branch that used the same agent and review type, and resumes that session instead of starting a new one.

The result is that the agent retains its prior conversation context (file contents it already read, architectural understanding it built up, earlier findings it made) and only needs to analyze what changed since the last review. This can substantially reduce token usage and review latency on active branches with frequent commits.

Enabling Session Reuse

Set reuse_review_session = true in your config:

# Per repo (.roborev.toml)
reuse_review_session = true

# Or globally (~/.roborev/config.toml)
reuse_review_session = true

How It Works

When a new review is enqueued, the daemon searches for a prior completed review on the same branch that matches the repo, agent, and review type. Candidates are checked newest-first and must pass two safety checks:

1. Ancestor check: The candidate’s reviewed commit must be an ancestor of the current target. This prevents reusing sessions from rebased or force-pushed branches where the history no longer applies.
2. Distance limit: The candidate must be within 50 commits of the current target. Sessions from much earlier in the branch history are too stale to provide useful context.

If a valid candidate is found, its session ID is passed to the agent, which resumes the prior conversation. If no candidate qualifies, the review starts fresh as usual.

Supported Agents

Session reuse requires agent-side support for resuming conversations. The following agents support it:

Agent	Resume mechanism
Codex	codex exec resume --json <session>
Claude Code	claude --resume <session>
OpenCode	opencode run --session <session>
Kilo	kilo run --session <session>
Pi	pi --session <path>

Agents that do not support session reuse (Gemini, Copilot, Cursor, Kiro, Droid) ignore the setting and always start fresh sessions.

Tuning with Lookback

By default, the daemon considers all prior sessions on the branch as candidates. On long-lived branches with many reviews, you can limit the search to the most recent N candidates:

reuse_review_session_lookback = 5   # Only consider 5 most recent sessions

This is rarely needed. The default (unlimited) works well because the ancestor and distance checks already filter out stale candidates.

Waiting for a Review Without Enqueuing

When a post-commit hook already triggers roborev review, you don’t need review --wait (which enqueues a duplicate job). Use roborev wait to block until the existing job completes:

roborev wait                     # Wait for most recent job for HEAD
roborev wait abc123              # Wait for job matching a specific commit
roborev wait --sha HEAD~1        # Explicit git ref
roborev wait --job 42            # Wait for a specific job ID
roborev wait --quiet             # Suppress output (exit code only)

Exit codes: 0 for PASS, 1 for FAIL or no job found.

Argument Resolution

A positional argument is resolved as a git ref first (so numeric SHAs like 123456 are handled correctly), then as a numeric job ID. Use --sha or --job to disambiguate when needed.

Agent Review-Fix Loops

roborev wait is designed for coding agents running review-fix refinement loops. The agent commits, the hook enqueues the review, and the agent calls wait to block until the verdict is ready. This avoids wasting tokens on repeated roborev list or roborev show invocations.

# Typical agent loop
git commit -m "Fix auth validation"   # Hook triggers review
roborev wait --quiet                  # Block until verdict
# Exit code 0 = pass, 1 = fail

When to use --wait

By default, roborev review enqueues reviews and returns immediately. The --wait flag blocks until the review completes and prints the result to stdout.

This is a convenience for:

• CI pipelines: gate merges on review outcomes using the exit code
• Orchestrators and one-shot agents: scripts or automated systems that need a synchronous result before proceeding
• roborev refine: the iterative fix loop uses --wait internally to re-review after each fix

--wait is not recommended inside interactive agent sessions (Claude Code, Codex, etc.). Reviews requested with --wait still appear in the TUI, but in practice the result scrolls past in the conversation and is easy to lose track of. The async workflow creates a persistent accountability loop: reviews stay open in the TUI queue until explicitly addressed and closed, so nothing falls through the cracks.

Exit Codes

When --wait is used, the exit code reflects the review verdict:

• Code 0 for passing reviews
• Code 1 for failing reviews

# CI example
if ! roborev review --branch --wait --quiet; then
    echo "Reviews found issues"
    exit 1
fi

Addressing Findings

After reviewing, use roborev fix to let an agent address any failed reviews:

roborev fix                      # Fix open reviews on this branch

Browse open reviews first with roborev tui, then fix them. See Responding to Reviews for the full set of options.

See Also

• Responding to Reviews: Fix findings and add comments
• Code Analysis & Refactoring: Targeted analysis with roborev analyze
• Auto-Fix with Refine: Automated fix loop
• Agent Skills: Review and fix from within an agent session