---
last_edited: 2026-09-17
---

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://roborev.io/docs/assets/static/logo-with-text-dark-bg.svg">
  <img alt="roborev" src="https://roborev.io/docs/assets/static/logo-with-text-light.svg">
</picture>

[![Go](https://img.shields.io/badge/Go-1.27.0+-00ADD8?logo=go&logoColor=white)](https://go.dev/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/Docs-roborev.io-blue)](https://roborev.io)

**[Documentation](https://roborev.io/docs/)** | **[Quick Start](https://roborev.io/docs/quickstart/)** | **[Installation](https://roborev.io/docs/installation/)**

Continuous code review for AI coding agents. roborev runs in the
background, reviews every commit as agents write code, and surfaces
issues in seconds -- before they compound. Pull code reviews into
your agentic loop while context is fresh.

![Roborev browser application](https://roborev.io/docs/assets/generated/web-ui.png)

## How It Works

1. Run `roborev init` to install a post-commit hook
2. Every commit triggers a background review -- agents write, roborev reads
3. View findings in the TUI, feed them to your agent, or let `roborev fix` handle it

### Automation, two layers

![How roborev works](https://roborev.io/docs/assets/static/how-it-works.svg)

- **Post-commit reviews** - a git hook reviews every commit in the background (any agent).
- **Agent hook** - watches supported coding-agent sessions and brings open
  roborev findings back into the active workflow.

```bash
roborev init                  # layer 1: per-commit reviews
roborev agent-hook install    # layer 2: wire agents and bundled skills
roborev agent-hook install --agent all  # or wire every supported profile
```

Before you ship, run the `/roborev-refine` skill: it re-reviews and fixes your
whole branch until every review passes, catching bugs before the PR.

New here? Run `roborev quickstart` and point your agent at it.

## Quick Start

```bash
cd your-repo
roborev init          # Install post-commit hook
git commit -m "..."   # Reviews happen automatically
roborev tui           # View reviews in interactive UI
roborev ui            # Open reviews in the native browser UI
```

If roborev is managed by a version manager, `roborev init` and
`roborev agent-hook install` try to install hooks with the stable shim/symlink.
You can also choose the exact binary path with
`roborev init --binary ~/.local/share/mise/shims/roborev`, or
`roborev agent-hook install --binary ~/.local/share/mise/shims/roborev`.

![roborev review](https://roborev.io/docs/assets/generated/tui-review.svg)

## Features

- **Background Reviews** - Every commit is reviewed automatically via
  git hooks. No remote review workflow required.
- **Auto-Fix** - `roborev fix` feeds review findings to an agent that
  applies fixes and commits. `roborev refine` iterates until reviews pass.
- **Agent Hook** - Optional hooks for Claude Code, Codex, Copilot CLI, Cursor,
  Factory Droid, Gemini CLI, Hermes, and Qwen bring open findings back into the
  active agent session.
- **Code Analysis** - Built-in analysis types (duplication, complexity,
  refactoring, test fixtures, dead code, security) that agents can fix
  automatically.
- **Multi-Agent** - Works with Codex, Claude Code, Gemini, Copilot,
  OpenCode, Cursor, Kiro, Kilo, Droid, and Pi.
- **Runs Locally** - No hosted service or additional infrastructure.
  Reviews are orchestrated on your machine using the coding agents
  you already have configured.
- **Interactive TUI** - Real-time review queue with vim-style navigation.
  Large terminals show the queue and selected review in a split-screen layout.
- **Native Browser UI** - Browse, filter, inspect, comment on, close, cancel,
  and rerun reviews from the application embedded in the local daemon, then
  explore cost, latency, reliability, and outcomes in Analytics.
- **Review Verification** - `roborev compact` verifies findings against
  current code, filters false positives, and consolidates related issues
  into a single review.
- **Review History Search** - Search completed reviews across repositories by
  keyword or meaning. Lexical search stays local and needs no embedding
  provider; semantic and hybrid modes are optional.
- **Extensible Hooks** - Run shell commands on review events. Built-in
  [beads](https://github.com/steveyegge/beads) and [kata](https://github.com/kenn-io/kata)
  integrations create trackable issues from review failures automatically.

## The Agentic Fix Loop

When reviews find issues, copy-and-paste the reviews into your
interactive agent sessions, or invoke `/roborev-fix` in Claude Code
or `$roborev-fix` in Codex. You can also address open reviews on the
command line non-interactively with `roborev fix`.

`roborev fix` shows the review findings to an agent, which applies
changes and commits. The new commit gets reviewed automatically,
closing the loop.

`roborev agent-hook install` auto-detects installed Claude Code, Codex, Copilot
CLI, Cursor, Factory Droid, Gemini CLI, Hermes, Qwen, and Grok Build harnesses
and adds optional hooks after configured turn, commit, or failed-review
thresholds are met. Reminders name exact review IDs, invoke the bundled
`roborev-fix` skill, and never run `roborev fix --open`. Hook installation
updates bundled skills for every supported profile. Hermes delivers queued
post-tool reminders at `Stop`; Cursor records the same events but emits no control
response.
Installed hooks post events to the regular roborev daemon. That daemon evaluates
the reminders and persists session counters and delivered review IDs in
`${ROBOREV_DATA_DIR:-~/.roborev}/agent-hook/state.json`. Hook callbacks fail open
when the daemon is unavailable, so they do not block the coding agent.

For fully automated iteration (advanced feature), use `refine`:

```bash
roborev refine                  # Fix, re-review, repeat until passing
roborev refine --plan            # Plan each fix before editing
roborev refine --plan-only       # Inspect plans for existing failed reviews
```

`refine` runs in an isolated worktree and loops: fix findings, wait for
re-review, fix again, until all reviews pass or `--max-iterations` is hit.

## Code Analysis

Run targeted analysis across your codebase and optionally auto-fix:

```bash
roborev analyze duplication ./...           # Find duplication
roborev analyze refactor --fix *.go         # Suggest and apply refactors
roborev analyze complexity --wait main.go   # Analyze and show results
roborev analyze test-fixtures *_test.go     # Find test helper opportunities
roborev analyze security ./...              # Find security risks in existing code
```

Available types: `test-fixtures`, `duplication`, `refactor`, `complexity`,
`api-design`, `dead-code`, `architecture`, `security`.

Analysis jobs appear in the review queue. Use `roborev fix` to apply
open findings later, target a specific job with `roborev fix <id>`, or
pass `--fix` to apply immediately.

Analysis types can pin their own agent settings in config:

```toml
[analyze.refactor]
agent = "claude-code"
model = "sonnet"
reasoning = "fast"
```

## Installation

**Shell Script (macOS / Linux):**
```bash
curl -fsSL https://roborev.io/install.sh | bash
```

**Homebrew (macOS / Linux):**
```bash
brew install kenn-io/tap/roborev
```

**Windows (PowerShell):**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://roborev.io/install.ps1 | iex"
```

**With Go:**
```bash
go install go.kenn.io/roborev/cmd/roborev@latest
```

The Go module source archive does not include generated browser assets. This
installation path provides the CLI and terminal UI; install a release package
or build with `make install` for the embedded browser application.

## Developer Setup

This repo uses [`prek`](https://prek.j178.dev/) for local Git hooks. Commits
run only the Renovate config validator and actionlint, and only when
`renovate.json` or a workflow file changes. The whole-repo checks run on push:
a Git-test isolation guard, `make lint-ci` for non-mutating Go lint,
`make markdown-ci` for Zensical Markdown formatting, and the web check and test
scripts when web files change. If you installed the hooks before, rerun
`prek install` to add the pre-push hook.

```bash
brew install prek uv  # or use your preferred install method
mise use --global npm:renovate@latest
prek install          # install the pre-commit and pre-push hooks
prek run --all-files --hook-stage pre-push  # run the push checks manually
```

Use `make lint` when you explicitly want golangci-lint to apply fixes. Use
`make markdown` to wrap prose in published Zensical pages at 80 columns while
leaving Markdown tables unchanged. Use `make check-renovate-config` to validate
`renovate.json` directly.

## Commands

| Command | Description |
|---------|-------------|
| `roborev init` | Initialize roborev in current repo |
| `roborev tui` | Interactive terminal UI |
| `roborev daemon status` | Show daemon, browser UI, and queue status |
| `roborev status` | Backward-compatible status alias |
| `roborev review <sha>` | Queue a commit for review |
| `roborev review --branch` | Review all commits on current branch |
| `roborev review --dirty` | Review uncommitted changes |
| `roborev fix` | Fix open reviews (or specify job IDs) |
| `roborev refine` | Auto-fix loop: fix, re-review, repeat |
| `roborev analyze <type>` | Run code analysis with optional auto-fix |
| `roborev agent-hook install` | Install hooks for detected coding agents |
| `roborev agent-hook install --agent all` | Install all nine supported integrations |
| `roborev snooze` | Silence Agent Hook reminders in the current worktree and branch |
| `roborev snooze off` | Resume Agent Hook reminders in the current worktree and branch |
| `roborev compact` | Verify and consolidate open review findings |
| `roborev show [sha]` | Display review for commit |
| `roborev search <query>...` | Search completed review history across repositories |
| `roborev export reviews` | Export completed reviews as JSON |
| `roborev export ci-metrics` | Export finalized CI panel metrics as JSON |
| `roborev export ci-costs` | Export job-level CI costs as JSON |
| `roborev run "<task>"` | Execute a task with an AI agent |
| `roborev close <id>` | Close a review |
| `roborev skills install` | Install bundled skills for supported agent profiles |

See [full command reference](https://roborev.io/docs/commands/) for all options.

Review history search is global by default and supports repository, branch,
time, verdict, and open/closed filters. Lexical search works with no provider
configuration or network call. See the
[search guide](https://roborev.io/docs/search/) for semantic and hybrid setup,
freshness, privacy, and recovery behavior.

### Exporting review history

Use `roborev export reviews` to emit completed reviews as one JSON document for
local reporting or archival workflows:

```bash
roborev export reviews
roborev export reviews --profile metadata --since 2026-06-01 --until 2026-06-30
roborev export reviews --closed-only --repo github.com/org/repo --limit 1000
roborev export reviews --cursor "$NEXT_CURSOR" --until 2026-07-01
```

The default `content` profile includes each review twice: `document` is the
stored JSON review document with the summary, verdict, and findings, and
`content` is the Markdown rendering of it. Review text may contain sensitive
repository details, so handle exported files carefully.
Use `--profile metadata` when you only need identifiers, timestamps, verdicts,
cost metadata, and related review metadata.

Exports include a stable `database_id` for the local review database and, when
at least one review is emitted, an opaque `next_cursor`. Pass
`--cursor <next_cursor>` to resume after the previous page; `--cursor` cannot
be combined with `--since`. If a cursor belongs to a previous database
generation, `roborev export reviews` exits with code `3`; discard the cursor
and retry with a window backfill. Other cursor rejections also require
discarding the cursor before backfilling.

Each exported review reports `closed` and `updated_at`. Closing or reopening a
review does not move it past a `completed_at` cursor, so combine the cursor pull
with `roborev export reviews --updated-since <time>` to pick up later close and
reopen changes. See the
[export reference](https://roborev.io/docs/commands/#exporting-reviews).

Use `roborev export ci-metrics` to emit finalized CI panel runs — terminal
outcome (`review_posted`, `no_review_posted`, `giveup_posted`, `abandoned`,
or `unknown` for panels finalized before outcomes were recorded),
first-attempt and posting timestamps, attempt count, and each panel's
member/synthesis jobs — for external review turnaround tracking.
`giveup_posted` is a historical outcome; exhausted retries now finish with
`no_review_posted` and an error status without a PR comment. The export follows
the same cursor contract as `roborev export reviews`, ordered by
`posted_at`, and exits with code `3` when a cursor's `database_id` no
longer matches so callers can discard the cursor and backfill.

Pass `--legacy` to export the frozen pre-panel CI era instead (rows with
outcome `legacy_review`, one per reviewed PR head, from before panel runs
existed) as a one-time backfill; legacy and panel cursors are namespaced
and cannot be resumed against each other's export.

Use `roborev export ci-costs` to emit cost-eligible CI jobs, including terminal
retry attempts that are no longer retained by a panel. Each row records its
completion time, agent, panel role, terminal status, and estimated USD cost.
Jobs whose agent ran but whose model cannot be priced remain present with
`cost_usd: null`; a reported free run is represented as `0`.

Cost rows are ordered by `(finished_at, job_id)` for stable pagination. A fresh
export over an overlapping window returns the current price for every matching
job, so idempotent consumers can pick up pricing recorded after an earlier
export. The export follows the same database-reset and opaque-cursor contract
as the other exports. `--legacy` selects the structurally identified pre-panel
CI era for a one-time historical backfill; regular and legacy cost cursors
cannot be mixed.

## Configuration

Create `.roborev.toml` in your repo:

```toml
agent = "claude-code"
snapshot_dir = ".roborev"
review_guidelines = """
Project-specific review instructions here.
"""
# Optional: use repo guidelines instead of appending global review_guidelines.
review_guidelines_supersede_global = false

# Optional: metadata for roborev-owned fix commits and prompt hints for agent-owned fix commits.
fix_commit_author = "Your Name <you@example.com>"
fix_commit_co_authored_by = ["Pair Reviewer <pair@example.com>"]
```

You can also set `review_guidelines` in `~/.roborev/config.toml`. Global
guidelines apply to every repo and are appended before repo guidelines by
default.

`snapshot_dir` must be repo-relative. `roborev init` ensures it is ignored in `.gitignore`; snapshot creation also adds a local `.git/info/exclude` fallback for existing checkouts whose ignore setup is stale.

See [configuration guide](https://roborev.io/docs/configuration/) for all options.

### Kata task context

If your repo is bound to a [kata](https://github.com/kenn-io/kata) project (a
committed `.kata.toml`), roborev can pull the kata issue(s) referenced in the
reviewed commit messages into the review prompt, and file review findings back
as kata issues.

```toml
# .roborev.toml
[kata_context]
mode = "current"   # off (default) | current | open
max_chars = 50000  # cap on kata context bytes in the prompt

# File a kata issue when a review fails or returns findings:
[[hooks]]
event = "review.*"
type = "kata"
# branches = ["main"]        # only file katas for reviews on these branches; default all
# project  = "myproj"        # defaults to the .kata.toml binding
# labels   = ["from-review"]
# priority = 2
```

`mode = "current"` includes only the katas referenced anywhere in the reviewed
commit messages (e.g. `Closes: kata#abc4`); `open` includes every open kata in
the bound project, except issues the kata hook itself filed (labelled
`roborev`), so review findings are not fed back into later reviews as task
intent. A hook's optional `branches` list (glob patterns such as `release/*`)
limits it to reviews on matching branches; unset fires on all branches. The
matched branch is the commit's branch for local reviews and the PR base
(target) branch for CI pull-request reviews — so `branches = ["main"]` means
commits on `main` locally but PRs *targeting* `main` in CI, and a fork's head
branch name cannot satisfy a protected-branch filter. The `kata` CLI must be
on `PATH`; when it is absent or the repo is unbound, prompt context is
silently skipped. Any other failure — a broken `.kata.toml`, a failing `kata`
invocation — is logged by both the prompt builder and the configured `kata`
hook, so a configured integration never goes dark unnoticed.

### Environment Variables

| Variable | Description |
|----------|-------------|
| `ROBOREV_DATA_DIR` | Override default data directory (`~/.roborev`) |
| `ROBOREV_COLOR_MODE` | TUI color theme: `auto` (default), `dark`, `light`, `none` |
| `ROBOREV_SYNC_CURSOR_LOOKBACK` | PostgreSQL sync cursor overlap duration (default `5m`) |
| `ROBOREV_AGENT_HOOK_TURN_THRESHOLD` | Override agent-hook Stop threshold |
| `ROBOREV_AGENT_HOOK_COMMIT_THRESHOLD` | Override agent-hook commit threshold |
| `ROBOREV_AGENT_HOOK_FAILED_REVIEW_THRESHOLD` | Override agent-hook failed-review threshold |
| `ROBOREV_AGENT_HOOK_ROBOREV_ADDR` | Override the regular daemon address used by Agent Hook |
| `ROBOREV_DROID_HOOK_TURN_THRESHOLD` | Override Factory Droid agent-hook Stop threshold |
| `ROBOREV_DROID_HOOK_COMMIT_THRESHOLD` | Override Factory Droid agent-hook commit threshold |
| `ROBOREV_DROID_HOOK_FAILED_REVIEW_THRESHOLD` | Override Factory Droid agent-hook failed-review threshold |
| `NO_COLOR` | Set to any value to disable all color output ([no-color.org](https://no-color.org)) |

## Supported Agents

| Agent | Install |
|-------|---------|
| Codex | `npm install -g @openai/codex` |
| Claude Code | `npm install -g @anthropic-ai/claude-code` |
| Gemini | `curl -fsSL https://antigravity.google/cli/install.sh \| bash` (preferred Antigravity CLI) or `npm install -g @google/gemini-cli` |
| Copilot | `npm install -g @github/copilot` |
| OpenCode | `npm install -g opencode-ai@latest` ([anomalyco/opencode](https://github.com/anomalyco/opencode)) |
| Cursor | [cursor.com](https://www.cursor.com/) |
| Kiro | [kiro.dev](https://kiro.dev/) |
| Kilo | `npm install -g @kilocode/cli` |
| Droid | [factory.ai](https://factory.ai/) |
| Pi | [pi.dev](https://pi.dev/) |

roborev auto-detects installed agents.

To use Pi as the auto-design routing classifier (`classify_agent = "pi"`),
install the JSON Schema output extension too:

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

roborev loads this extension explicitly when it invokes the classifier. Keeping
it installed in Pi makes the classifier setup visible in `pi list` and avoids
runtime package-fetch surprises in offline or locked-down environments.

### Routing Claude Code to a proxy (Ollama, LiteLLM, etc.)

The `claude-code` agent accepts a model spec of the form `<model>@<base_url>`.
When `<base_url>` starts with `http(s)://`, roborev points Claude Code at
that endpoint and pins all tier aliases (Opus/Sonnet/Haiku/subagent) to the
given model.

```toml
# .roborev.toml — local Ollama for reviews, real Anthropic for fixes
agent = "claude-code"
review_model = "glm-5.1:cloud@http://127.0.0.1:11434"
fix_model    = "sonnet"
```

Or via CLI: `roborev review --model 'glm-5.1:cloud@http://127.0.0.1:11434'`.

**Proxy auth.** Set `ROBOREV_CLAUDE_PROXY_TOKEN` to forward a bearer token
to the proxy as `ANTHROPIC_AUTH_TOKEN`. If unset, roborev sends a placeholder
(sufficient for gateways that don't check the header, such as Ollama).
roborev does *not* forward `ANTHROPIC_API_KEY` to proxy endpoints — that
would leak a real Anthropic credential to arbitrary third parties.

**URL restrictions.** Proxy URLs must not embed `user:pass@` credentials
(use `ROBOREV_CLAUDE_PROXY_TOKEN`); `http://` is only accepted for loopback
hosts (`127.0.0.1`, `::1`, `localhost`) so plaintext endpoints can't receive
tokens over the wire. Use `https://` for remote proxies. The full URL
(including any path or query string) is forwarded as-is to
`ANTHROPIC_BASE_URL`, so include the path your gateway expects (e.g.
LiteLLM may want a trailing `/v1`; Ollama wants no path).

**Environment behavior (breaking change in this release).** When the
`claude-code` agent runs, roborev always strips inherited `ANTHROPIC_API_KEY`,
`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`,
`ANTHROPIC_DEFAULT_{OPUS,SONNET,HAIKU}_MODEL`, and `CLAUDE_CODE_SUBAGENT_MODEL`
from the child environment. If you were previously routing Claude Code by
exporting these vars in your shell, switch to the `<model>@<base_url>` spec
instead. For native (non-proxy) mode, configure `ANTHROPIC_API_KEY` via
roborev's config (it is re-injected from roborev's stored key, not inherited
from the operator's shell).

## Telemetry

roborev sends limited anonymous telemetry to PostHog when the daemon starts
and once every 24 hours while the daemon remains running: `daemon_started`
and `daemon_active` with repo count, review count, sync enabled, CI
enabled, and auto-design enabled, plus `application=roborev`, version, OS/arch,
`$process_person_profile=false`, `$geoip_disable=true`, and an anonymous install
ID.
The web UI also asks the daemon to report an `app_opened` event when it loads
and on the first window focus of each later UTC day, and `roborev tui` asks each
time it starts. CLI commands that work through the daemon ask after their first
successful daemon request, without starting a daemon; hook, MCP and daemon
management commands, and commands the bundled agent skills run with
`--from-skill`, do not. The daemon sends at most one `app_opened` per surface
per UTC day, so repeated opens on the same day count once, with the same install
ID and default fields plus `surface` (`web`, `tui` or `cli`). The browser, the TUI and the CLI only talk to the daemon; the TUI and the
CLI also send nothing when either opt-out variable is set in their own
environment.
Each event also carries `install_age_hours`, the whole hours since the install
was created, so short-lived installs such as test sandboxes can be filtered out.
It does not send repo names, paths, remotes, prompts, review output, provider
tokens, usernames, or IP geolocation. Set `ROBOREV_TELEMETRY_ENABLED=0` to
disable it. `TELEMETRY_ENABLED=0` is also honored. Telemetry is always disabled
inside Go test processes, regardless of environment variables.

## Security Model

roborev delegates code review and fix tasks to AI coding agents that
have shell access. Review agents may execute read-only git and shell
commands to inspect diffs; fix agents run in isolated worktrees with
full tool access.

**roborev is designed for use with trusted codebases.** The review
prompt includes diff content and commit messages from the repository.
If you are reviewing untrusted code (e.g., open-source contributions
from unknown authors), run roborev inside a sandboxed environment
(container, VM, or similar) to limit the blast radius of any
prompt-injection attack that could cause an agent to execute
unintended commands.

## Documentation

Full documentation available at **[roborev.io](https://roborev.io)**:

- [Quick Start](https://roborev.io/docs/quickstart/)
- [Installation](https://roborev.io/docs/installation/)
- [Commands Reference](https://roborev.io/docs/commands/)
- [Configuration](https://roborev.io/docs/configuration/)
- [Auto-Fixing with Refine](https://roborev.io/docs/guides/auto-fixing/)
- [Code Analysis and Assisted Refactoring](https://roborev.io/docs/guides/assisted-refactoring/)
- [Hooks](https://roborev.io/docs/guides/hooks/)
- [Agent Hook](https://roborev.io/docs/agent-hook/)
- [Agent Skills](https://roborev.io/docs/guides/agent-skills/)
- [PostgreSQL Sync](https://roborev.io/docs/advanced/postgres-sync/)

For local development in this repo, install hooks with `prek install` or run
`make install-hooks` as a thin wrapper around `prek install`.

## License

MIT