revue

Agentic PR review CLI for large codebases. Runs 5 specialist AI agents in parallel, uses adversarial debate to eliminate false positives, and costs ~$0.35--0.90 per review.

npm install -g revue   # or: git clone && npm install && npm link
export ANTHROPIC_API_KEY=sk-ant-...
revue review --pr 123 --repo owner/repo

Overview

Revue is a command-line tool that performs deep, multi-agent code review on pull requests and local diffs. It is designed for large codebases where a single-pass LLM review misses context.

Key differentiators:

5 specialist agents run in parallel, each focused on a single concern (security, correctness, performance, API contracts, test coverage).
Adversarial debate challenges all critical/warning findings against the actual diff, reducing false positives. Based on research showing detection rates jump from 53% to 80%.
Blast radius analysis detects when a function signature changes and automatically finds every caller outside the diff that would break.
Backward program slicing walks def-use chains from changed lines to include only the code the LLM actually needs to see.
PageRank repo map builds a symbol index ranked by structural importance, giving agents a bird's-eye view of the codebase.
Model cascade uses a cheap model (Haiku) to triage files before spending tokens on deep review, saving 60-80% on large PRs.
Two-layer prompt caching caches system prompts and PR-level context across all agent calls, achieving ~89% input token savings.
Hard cap at 10 findings prevents alert fatigue (research shows reviewers ignore findings beyond ~10).
Crash recovery logs every pipeline stage to disk. If a review crashes mid-run, --resume picks up where it left off.
Multi-provider support for Anthropic (Claude), OpenAI (GPT/o-series), and Google (Gemini) models.

Installation

# Clone and build
git clone <repo-url>
cd pr-review-ui
npm install
npm run build

# Make `revue` available globally
npm link

# Verify installation
revue --version    # should print 0.1.0
revue --help

Requirements: Node.js 18+, git.

Quick Start

Set your API key:
```
export ANTHROPIC_API_KEY=sk-ant-...
```
Review your current branch against main:
```
revue diff
```

Review a GitHub PR:

export GITHUB_TOKEN=ghp_...
revue review --pr 42 --repo myorg/myrepo

Post review comments directly to GitHub:

revue review --pr 42 --repo myorg/myrepo --post

Supported Models & Providers

Revue supports three LLM providers. The provider is auto-detected from the model name, or can be set explicitly via the provider config key.

Anthropic (Claude)

Model	Pricing (per 1M tokens)	Notes
`claude-sonnet-4-20250514`	$3 input / $15 output / $0.30 cached	Default model. Best balance of quality and cost.
`claude-haiku-4-5-20251001`	$0.80 input / $4 output / $0.08 cached	Default triage model. Used for file classification in the cascade.
`claude-opus-4-20250514`	$15 input / $75 output / $1.50 cached	Highest quality. Use for critical codebases where cost is not a concern.

OpenAI (GPT / o-series)

Model	Pricing (per 1M tokens)	Notes
`gpt-4o`	$2.50 input / $10 output	Strong general-purpose model.
`gpt-4o-mini`	$0.15 input / $0.60 output	Good for triage. Set as `triageModel`.
`o3-mini`	$1.10 input / $4.40 output	Reasoning model with strong code analysis.

Google (Gemini)

Model	Pricing (per 1M tokens)	Notes
`gemini-2.5-pro`	$1.25 input / $10 output	Large context window, strong code understanding.
`gemini-2.5-flash`	$0.15 input / $0.60 output	Fast and cheap. Good for triage.
`gemini-2.0-flash`	$0.10 input / $0.40 output	Fastest Gemini model.

Provider auto-detection

The provider is inferred from the model name prefix:

Prefix	Provider
`claude-*`	Anthropic
`gpt-`, `o1-`, `o3-`, `o4-`	OpenAI
`gemini-*`	Google

You can override this by setting provider to "anthropic", "openai", "gemini", or "auto" (the default).

Commands

`revue review`

Review a GitHub pull request.

revue review --pr <number> --repo <owner/repo> [options]

Required flags:

Flag	Description
`--pr <number>`	PR number to review.
`--repo <owner/repo>`	Repository in `owner/repo` format.

Optional flags:

Flag	Default	Description
`--post`	`false`	Post review findings as comments on the GitHub PR.
`--incremental`	`false`	Only review changes since the last revue review on this PR. Compares the current HEAD against the commit SHA from the previous review.
`--model <model>`	`claude-sonnet-4-20250514`	LLM model to use for deep review.
`--agents <list>`	all 5	Comma-separated list of agents to run. Valid values: `security`, `correctness`, `performance`, `api-contract`, `test-coverage`.
`--no-debate`	debate enabled	Disable the adversarial debate stage. Faster, but more false positives.
`--no-cascade`	cascade enabled	Disable Haiku triage. All files get reviewed by all agents. More thorough but more expensive.
`--test-gen`	`false`	Generate regression tests for changed functions after review.
`--json`	`false`	Output the full review result as JSON instead of the formatted terminal view.
`--log <path>`	auto-generated	Path for the JSONL review log file. Default: `.revue/logs/review-YYYY-MM-DDTHHMMSS.jsonl`.
`--resume <path>`	none	Resume a crashed or interrupted review from a log file. Skips already-completed stages.

Examples:

# Basic review
revue review --pr 123 --repo myorg/myrepo

# Post to GitHub with only security and correctness agents
revue review --pr 123 --repo myorg/myrepo --post --agents security,correctness

# Incremental review (only new changes since last review)
revue review --pr 123 --repo myorg/myrepo --incremental

# Use Opus for maximum quality
revue review --pr 123 --repo myorg/myrepo --model claude-opus-4-20250514

# Use GPT-4o
revue review --pr 123 --repo myorg/myrepo --model gpt-4o

# JSON output for CI integration
revue review --pr 123 --repo myorg/myrepo --json > review.json

# Generate tests alongside review
revue review --pr 123 --repo myorg/myrepo --test-gen

# Resume a crashed review
revue review --pr 123 --repo myorg/myrepo --resume .revue/logs/review-2026-03-18T143022.jsonl

`revue diff`

Review a local diff without GitHub. Reads from a file, stdin, or generates a diff against a branch.

revue diff [options]

Optional flags:

Flag	Default	Description
`--file <path>`	none	Path to a unified diff file. If omitted and stdin is not a pipe, generates a diff from git.
`--branch <name>`	`main`	Base branch to diff against when generating from git. Runs `git diff <branch>...HEAD`.
`--model <model>`	`claude-sonnet-4-20250514`	LLM model to use.
`--agents <list>`	all 5	Comma-separated agent list.
`--no-debate`	debate enabled	Disable adversarial debate.
`--no-cascade`	cascade enabled	Disable triage cascade.
`--test-gen`	`false`	Generate regression tests for changed functions.
`--json`	`false`	Output as JSON.
`--log <path>`	auto-generated	Path for the review log file.
`--resume <path>`	none	Resume from a log file.

Examples:

# Review current branch against main (most common usage)
revue diff

# Review against a specific branch
revue diff --branch develop

# Review a diff file
revue diff --file changes.diff

# Pipe from git
git diff main...HEAD | revue diff

# Pipe a staged diff
git diff --cached | revue diff

# Fast review: skip debate, skip triage
revue diff --no-debate --no-cascade

# Use Gemini
revue diff --model gemini-2.5-pro

`revue dry-run`

Analyze a diff without making any LLM calls. Shows what each agent would see, token estimates, file classifications, and cost projections. No API key required.

revue dry-run [options]

Optional flags:

Flag	Default	Description
`--file <path>`	none	Path to a diff file.
`--branch <name>`	`main`	Base branch to diff against.
`--dump <dir>`	none	Dump the full rendered prompts (system + user) to the specified directory for manual inspection.
`--model <model>`	`claude-sonnet-4-20250514`	Model to use for cost estimation.
`--agents <list>`	all 5	Agents to simulate.
`--no-debate`	debate enabled	Exclude debate from the cost projection.
`--no-cascade`	cascade enabled	Exclude triage from the cost projection.
`--json`	`false`	Output the dry-run report as JSON.

Examples:

# See what agents would receive
revue dry-run

# Dry run against a different branch
revue dry-run --branch develop

# Dump prompts to disk for inspection
revue dry-run --dump /tmp/revue-prompts

# JSON output for scripting
revue dry-run --json

# Dry run a diff file
revue dry-run --file my-changes.diff

`revue ui`

Start a web dashboard that displays review progress and results in real time. The dashboard connects via Server-Sent Events (SSE) to tail the JSONL review log.

revue ui [options]

Optional flags:

Flag	Default	Description
`--port <port>`	`3000`	Port to listen on. If the port is in use, revue will try ports 3001--3010 automatically.
`--log-file <path>`	most recent log	Specific JSONL log file to tail. If omitted, tails the most recent file in `.revue/logs/`.
`--no-open`	auto-opens	Do not automatically open the dashboard in the default browser.

Examples:

# Start dashboard (auto-opens browser)
revue ui

# Start on a specific port without opening browser
revue ui --port 8080 --no-open

# Tail a specific log file
revue ui --log-file .revue/logs/review-2026-03-18T143022.jsonl

Configuration

.revuerc File

Place a .revuerc file (JSON) in the root of your repository to set defaults. Every key is optional.

{
  "anthropicApiKey": "sk-ant-...",
  "openaiApiKey": "sk-...",
  "geminiApiKey": "AIza...",
  "provider": "auto",
  "githubToken": "ghp_...",
  "model": "claude-sonnet-4-20250514",
  "triageModel": "claude-haiku-4-5-20251001",
  "maxConcurrentAgents": 5,
  "agents": ["security", "correctness", "performance", "api-contract", "test-coverage"],
  "severityThreshold": "suggestion",
  "confidenceThreshold": 0.3,
  "enableDebate": true,
  "enableCascade": true,
  "enableTestGen": false,
  "repoMapTokenBudget": 12000,
  "chunkTokenBudget": 32000
}

Environment Variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	Yes (if using Anthropic)	Anthropic API key for Claude models.
`OPENAI_API_KEY`	Yes (if using OpenAI)	OpenAI API key for GPT/o-series models.
`GEMINI_API_KEY`	Yes (if using Google)	Google API key for Gemini models.
`GITHUB_TOKEN`	For `review` command	GitHub personal access token. Needs `repo` scope for private repos.
`REVUE_VERBOSE`	No	Set to `1` for debug logging.

Config Precedence

Configuration is resolved in this order, with later sources overriding earlier ones:

Built-in defaults (see table below)
.revuerc file in the current working directory
Environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GITHUB_TOKEN)
CLI flags (highest priority)

Full RevueConfig Schema

Key	Type	Default	Description
`anthropicApiKey`	`string`	`""`	Anthropic API key. Usually set via `ANTHROPIC_API_KEY` env var.
`openaiApiKey`	`string`	`""`	OpenAI API key. Usually set via `OPENAI_API_KEY` env var.
`geminiApiKey`	`string`	`""`	Google Gemini API key. Usually set via `GEMINI_API_KEY` env var.
`provider`	`"anthropic" \| "openai" \| "gemini" \| "auto"`	`"auto"`	LLM provider. `"auto"` infers from the model name prefix.
`githubToken`	`string`	`""`	GitHub token. Usually set via `GITHUB_TOKEN` env var.
`model`	`string`	`"claude-sonnet-4-20250514"`	Model used for deep review by all specialist agents.
`triageModel`	`string`	`"claude-haiku-4-5-20251001"`	Model used for the triage cascade (file classification). Should be a cheap, fast model.
`maxConcurrentAgents`	`number`	`5`	Maximum number of agent LLM calls running in parallel. Lower this if you hit rate limits.
`agents`	`AgentKind[]`	`["security", "correctness", "performance", "api-contract", "test-coverage"]`	Which specialist agents to run.
`severityThreshold`	`"critical" \| "warning" \| "suggestion" \| "nitpick"`	`"suggestion"`	Minimum severity for a finding to appear in the output. Findings below this threshold are suppressed.
`confidenceThreshold`	`number`	`0.3`	Minimum confidence (0--1) for a finding to appear. Findings below this are suppressed.
`enableDebate`	`boolean`	`true`	Enable the adversarial debate stage that challenges critical/warning findings.
`enableCascade`	`boolean`	`true`	Enable the Haiku triage cascade. When disabled, all files are reviewed by all agents.
`enableTestGen`	`boolean`	`false`	Generate regression tests for changed functions.
`repoMapTokenBudget`	`number`	`12000`	Maximum tokens allocated to the PageRank repo symbol map.
`chunkTokenBudget`	`number`	`32000`	Maximum tokens per agent chunk. Files are split across chunks when the total exceeds this budget.

Review Pipeline

The review pipeline runs through 9 stages in sequence. Each stage is described below.

1. Diff Parsing

The unified diff (from GitHub API or local git) is parsed into structured DiffFile objects. Each file contains hunks, and each hunk contains typed lines (add, delete, context) with both old and new line numbers. Binary files are skipped. File status is tracked as added, modified, deleted, or renamed.

2. Context Retrieval

For each changed file, 8 analyses run in parallel to build a rich FileContext:

Analysis	What it produces	Purpose
AST parsing	Changed symbols (functions, classes, methods, interfaces, types), affected exports, intra-file call graph.	Tells agents exactly which symbols changed and how they connect.
Git blame	Author, date, and commit hash for each changed line.	Surfaces recent churn and identifies who last touched the code.
Dependency tracing	`imports` (what this file imports) and `importedBy` (what imports this file).	Reveals coupling and helps assess blast radius.
Blast radius	Detects signature/return-type/removal/rename changes to exported functions, then uses `git grep` to find every call site outside the diff (up to 50 callers). Each caller includes a 30-line code snippet.	Catches breaking changes that the diff alone would hide.
Backward program slice	Starting from changed lines, walks backward through def-use chains to find all variable definitions, enclosing function signatures, and callee definitions. Produces annotated code regions with reasons.	Replaces naive "surrounding code" with exactly the code needed to understand the change, typically 60-80% less noise.
Surrounding code	50 lines of context above and below each hunk (used as fallback when the slicer produces no results).	Ensures agents always have enough context.
PageRank repo map	A 2-hop neighborhood of files related to the changed files (up to 500 files), with symbols extracted and ranked by PageRank. Biases rank toward changed files. Fits within a configurable token budget (default 12K).	Gives agents a codebase-level overview of the most important symbols.
Co-change analysis	Identifies files that historically change together with the modified files but are missing from the current PR.	Catches potentially forgotten files.
Static analysis	Runs `tsc` and `eslint` (if available) on changed files and collects diagnostics.	Provides compiler/linter warnings as additional signal for agents.

3. File Ordering

Files are sorted before being fed to agents using a blended score:

Core score (40%): Files that other changed files depend on rank higher. Computed as: (blast radius exports * 10) + (intra-change importers * 5) - (intra-change imports * 3).
Composite risk score (30%): Based on change entropy (how spread out the changes are) and blast radius.
TF-IDF info scent (30%): Semantic relevance of each file's path and symbols to the PR title. Files whose names/symbols are most related to the PR description rank higher.

This ensures the "origin" files (the ones that drive the change) are reviewed first, giving agents better context for downstream files.

4. Triage Cascade

When cascade is enabled (default) and the PR has more than 3 files, a cheap model (default: Claude Haiku) classifies each file into one of four levels:

Level	Description	Which agents run
`critical`	Security-sensitive, API/export changes, database migrations, files with blast radius.	All 5: security, correctness, performance, api-contract, test-coverage
`review`	Business logic, non-trivial refactors, error handling, new features.	4: correctness, performance, api-contract, test-coverage
`low-risk`	Test files, documentation, minor refactors, style changes.	1: test-coverage
`skip`	Auto-generated files, lock files, cosmetic-only changes, comments-only.	None

The triage prompt includes each file's change entropy, composite risk score, export change flags, and blast radius flags to help the model make accurate classifications.

Override: Files with blast radius (changed exports with external callers) are always forced to critical regardless of the model's classification.

Cost savings: On a 50-file PR where 30 files are low-risk or skippable, triage saves 60-80% of review tokens.

5. Knapsack Compression

After triage, files within each level are compressed into token-budget chunks using a greedy knapsack algorithm:

Value = composite risk score (entropy + blast radius + coupling).
Weight = estimated token cost of the file's full context.
Budget = chunkTokenBudget (default: 32,000 tokens per chunk).

Files that individually exceed 50% of the chunk budget are truncated: surrounding code is trimmed and blast radius callers are capped at 5. Files that still exceed the budget after truncation are placed in an overflow list and excluded from the review.

When all files for a triage level fit in a single chunk, agents make one LLM call. When they span multiple chunks, agents make one call per chunk and results are merged.

6. Prompt Caching

Revue uses a two-layer prompt caching strategy to minimize token costs across multiple LLM calls:

Layer 1 (system prompt): The agent's system prompt (review guidelines, output schema) is marked with cache_control: ephemeral. This is identical across all calls for the same agent, so it is cached after the first call.
Layer 2 (PR context): The repo map and co-change analysis are stable across all files in the same PR. They are sent as a cached user message prefix.
Layer 3 (per-file diff): The actual diff and file context are dynamic and never cached.

With 5 agents reviewing 20 file chunks (100 LLM calls), layers 1 and 2 are cache hits on 99 of them. At Sonnet pricing, this achieves approximately 89% cost reduction on input tokens.

7. Specialist Agents

Five specialist agents review the code in parallel (concurrency controlled by maxConcurrentAgents):

Security Agent

Looks for:

Injection attacks: SQL injection, XSS, command injection, path traversal
Authentication and authorization flaws
Hardcoded secrets or credentials
Unsafe deserialization
SSRF, open redirects
Cryptographic misuse (weak algorithms, improper key handling)
Input validation gaps at system boundaries

Only flags genuine security concerns with specific evidence from the code. Requires a concrete attack vector and impact assessment.

Correctness Agent

Looks for:

Logic errors, off-by-one mistakes, incorrect conditions
Null/undefined handling, missing nil checks
Type mismatches or unsafe casts
Error handling gaps (uncaught exceptions, swallowed errors)
Race conditions in concurrent/async code
State mutation bugs
Boundary conditions and edge cases

Blast radius handling: When the blast radius section is present, the correctness agent examines every caller shown in "Callers Outside Diff" and flags each broken caller as a separate critical finding.

Performance Agent

Looks for:

N+1 query patterns or unbatched I/O
Unnecessary memory allocations, large object copies
Algorithm complexity regressions (O(n^2) where O(n) is possible)
Missing indexes for database queries
Unbounded loops or collections
Memory leaks (unclosed resources, dangling listeners)
Blocking operations in async contexts
Bundle size impact for frontend code

Only flags issues that would have measurable impact. Ignores micro-optimizations.

API Contract Agent

Looks for:

Breaking changes to public APIs (removed/renamed exports, changed signatures)
Request/response schema changes that break consumers
Missing backward compatibility for existing clients
Version bumps needed but not made
GraphQL/REST contract violations
Type export changes that affect downstream packages

Blast radius handling: Examines every caller in the blast radius, categorizes breaks as compile-time (caught by types, severity: warning) vs. runtime (silent failure, severity: critical). If more than 10 callers are affected, recommends a migration strategy.

Test Coverage Agent

Looks for:

Changed functions/methods with no corresponding test changes
New code paths without tests
Edge cases and error paths not covered
Test changes that test the wrong thing

Provides specific, actionable suggestions: names the function, the scenario, and the assertion needed.

8. Adversarial Debate

After all agents complete, findings with severity critical or warning enter the adversarial debate. Lower-severity findings pass through unchanged.

The debate uses a single judge pass:

All critical/warning findings are collected with their full context.
A judge LLM (using the main review model) receives each finding along with the actual diff.
For each finding, the judge:
- Verifies the finding against the real code.
- Plays adversary: tries to prove the finding wrong by checking if the code is actually safe, if surrounding context invalidates the concern, if the issue is purely theoretical, or if the severity is overstated.
- Plays defender: considers why the finding might still be valid.
- Renders a verdict: valid, weakened, or refuted.
- Assigns adjusted confidence (0--1).

Verdict effects:

Verdict	Effect
`valid`	Confidence boosted by +0.1 (capped at 1.0). Finding marked as `verified: true`.
`weakened`	Confidence reduced to `min(adjusted, original * 0.8)`. Finding kept but downgraded.
`refuted`	Finding removed entirely.

Findings that receive no verdict from the judge (e.g., due to output truncation) are kept with verified: false.

9. Synthesis

The final stage merges, filters, deduplicates, and caps findings:

Confidence calibration: Uses ReConcile-style weighted consensus. When multiple agents flag the same location (overlapping lines within 3 lines), the probability that at least one agent is correct is computed as P = 1 - product(1 - conf_i). Each finding's confidence is boosted toward the consensus.
Threshold filtering: Findings below severityThreshold or confidenceThreshold are suppressed.
Deduplication: Findings at the same file/line with similar titles (first 30 characters) are deduplicated, keeping the highest-severity one.
Sorting: Critical first, then by file and line number.
Hard cap at 10: Findings are scored by (3 - severityRank) * confidence and the top 10 are kept. The count of suppressed findings is reported.
Summary generation: A template-based summary is generated with severity counts and top finding titles. If the template produces fewer than 80 characters, an LLM fallback generates a 2--4 sentence summary.

Web Dashboard

The revue ui command starts a local web server that displays review progress in real time.

revue ui

The dashboard provides:

Live event stream: Connects via Server-Sent Events (SSE) to tail the active JSONL review log. Events appear as they are written, so you can watch triage, agent completions, debate results, and synthesis in real time.
Log browser: Lists all review logs in .revue/logs/ sorted by most recent. You can select any past log to view its full event history.
Review details: Displays PR info, triage classifications, per-agent findings, debate verdicts, final synthesized findings, and cost breakdown.

Server behavior:

Listens on 127.0.0.1 only (not exposed to the network).
Default port is 3000. If 3000 is in use, automatically tries ports 3001 through 3010.
Sends SSE keepalive pings every 15 seconds.
If the log file does not exist yet (review hasn't started), the server polls every 500ms until it appears.
Ctrl+C shuts down the server cleanly.

Endpoints:

Path	Method	Description
`/`	GET	Serves the dashboard HTML page.
`/events?file=<path>`	GET	SSE stream tailing the specified log file. If `file` is omitted, tails the most recent log.
`/api/logs`	GET	JSON array of all log files with paths, modification times, and sizes.

Review Logging & Crash Recovery

Every review automatically writes a JSONL (JSON Lines) log file to .revue/logs/. Each line is a self-contained JSON event.

Log file location

Default: .revue/logs/review-YYYY-MM-DDTHHMMSS.jsonl (auto-generated timestamp)
Custom: --log /path/to/my-review.jsonl

Event types

Event	Fields	Description
`review_start`	`pr`, `fileCount`, `files`	Emitted when the review begins. Records PR info and all changed files.
`context_complete`	`files`	Emitted after context retrieval finishes.
`triage_complete`	`levels`	Records the triage classification for each file (a `Record<string, TriageLevel>`).
`agent_complete`	`result`	Emitted each time an agent finishes. Contains the full `AgentResult` with findings, token usage, and duration.
`agent_failed`	`agent`, `error`	Emitted when an agent throws an error.
`debate_complete`	`results`	Records all agent results after the debate stage.
`synthesis_complete`	`result`	Records the final `ReviewResult` with all findings, summary, and stats.
`cost_report`	`report`	Final cost breakdown (tokens, calls, estimated USD).

All events include a timestamp field (ISO 8601).

Crash recovery with `--resume`

If a review crashes (network error, rate limit, process kill), you can resume it:

revue review --pr 123 --repo myorg/myrepo --resume .revue/logs/review-2026-03-18T143022.jsonl

The resume logic reads the log file and restores:

Triage classifications (skips re-triage)
Completed agent results (skips re-running those agents)
Debate results (skips re-running debate if already done)
Synthesis result (returns immediately if the review was already complete)

Only incomplete stages are re-run. Malformed log lines (from partial writes during a crash) are silently skipped.

Cost Control

Revue uses several strategies to minimize API costs:

Strategy	Savings	How it works
Model cascade	60--80%	Haiku triage (~$0.001 per PR) classifies files. Low-risk files get only 1 agent; skipped files get none.
Prompt caching	~89% of input tokens	System prompt + PR context are cached across all agent calls. Only per-file diffs are fresh.
Knapsack compression	Variable	High-risk files get more context budget. Low-risk files get truncated. Overflow files are excluded.
Backward slicing	60--80% of context	Replaces naive surrounding code with only the lines relevant to the change.
Hard cap	Prevents waste	Max 10 findings per review. No tokens spent generating findings that would be suppressed.
Agent routing	40--80%	Triage determines which agents run per file. Low-risk files skip security, performance, api-contract, and correctness agents entirely.

Typical costs (Anthropic Claude Sonnet)

PR size	Files	Estimated cost
Small	1--5 files	~$0.35
Medium	10--20 files	~$0.50
Large	40--70 files	~$0.90
Very large	100+ files	~$1.50--2.00

Costs are lower with cheaper models (Haiku, GPT-4o-mini, Gemini Flash). The cost report printed after every review shows exact token counts, cache hit rates, and estimated USD.

Output Formats

Terminal (default)

Findings are grouped by file, with severity icons, line numbers, agent names, confidence percentages, and verification status. A stats footer shows agent count, finding count, total tokens, and wall-clock time. A cost footer shows LLM call counts, token breakdown, cache hit rate, and estimated cost.

JSON (`--json`)

Outputs the full ReviewResult object:

{
  "pr": { "owner": "...", "repo": "...", "number": 123, ... },
  "findings": [
    {
      "id": "uuid",
      "agent": "correctness",
      "severity": "critical",
      "confidence": 0.92,
      "file": "src/auth.ts",
      "line": 45,
      "title": "Missing null check on user object",
      "description": "...",
      "suggestion": "...",
      "reasoning": "...",
      "verified": true
    }
  ],
  "summary": "...",
  "agentResults": [...],
  "totalTokens": { "input": 45000, "output": 3200 },
  "totalDurationMs": 12400,
  "suppressedCount": 3,
  "generatedTests": [...]
}

GitHub PR Comments (`--post`)

When --post is used with the review command, findings are posted as a GitHub PR review with:

A summary comment with a severity breakdown table
Inline comments on the relevant lines with finding details and suggestions

Incremental Reviews

The --incremental flag (available on the review command) enables incremental reviews that only analyze changes since the last revue review.

How it works:

Revue looks for the commit SHA of the most recent revue review on the PR.
It computes the delta (files changed between that SHA and the current HEAD).
The diff is filtered to only include files in the delta.
The filtered diff is reviewed normally through the full pipeline.

If no previous review is found, a full review is performed.

This is useful for large PRs that go through multiple review cycles. Instead of re-reviewing the entire PR after each push, --incremental focuses on what actually changed.

Test Generation

The --test-gen flag enables automatic regression test generation after the review.

How it works:

After all agents complete, files classified as critical or review are selected.
A test generation prompt is built with each file's diff, surrounding code, changed symbols (with signatures), and import list.
An LLM generates minimal regression tests that exercise the NEW behavior introduced by the changes.

Test generation rules:

Tests verify new/changed behavior, not old behavior.
Edge cases visible in the diff are included (boundary values, null checks, error paths).
The project's test framework is inferred from imports and file patterns (Jest, Vitest, Mocha, pytest, Go testing, etc.).
One test per changed behavior, with descriptive names: "should [expected behavior] when [condition]".
Only functions actually changed in the diff get tests.

Output: Each generated test includes the source file it covers, the function name, a description of what it verifies, and the complete test code. Tests are printed after the review findings in terminal mode, or included in the generatedTests array in JSON mode.

revue diff --test-gen
revue review --pr 42 --repo o/r --test-gen

Project Structure

src/
├── cli.ts                     CLI entry point (review, diff, dry-run, ui commands)
├── dry-run.ts                 Full pipeline without LLM calls
├── types.ts                   All shared TypeScript types
├── config.ts                  .revuerc loading, env vars, validation, defaults
├── diff/
│   ├── parser.ts              Unified diff parser -> structured DiffFile/DiffHunk/DiffLine
│   └── delta.ts               Incremental review: compute delta between SHAs
├── context/
│   ├── retriever.ts           Parallel context assembly, file ordering, info scent
│   ├── slicer.ts              Backward program slicer (def-use chains)
│   ├── ast.ts                 AST-based symbol extraction + call graph
│   ├── blast-radius.ts        Signature change detection + caller discovery
│   ├── static-analysis.ts     tsc + eslint diagnostic integration
│   ├── blame.ts               Git blame for changed regions
│   ├── deps.ts                Import/export dependency tracing
│   ├── co-change.ts           Git history coupling analysis
│   ├── compression.ts         Knapsack-based PR compression into token chunks
│   └── repo-map.ts            PageRank-ranked symbol index (2-hop neighborhood)
├── agents/
│   ├── base.ts                ReviewAgent class with structured LLM output
│   ├── orchestrator.ts        Triage -> fan-out -> debate -> test-gen pipeline
│   ├── triage.ts              Haiku-based file risk classification
│   ├── debate.ts              Adversarial judge with challenge/defense
│   └── test-gen.ts            Regression test generation
├── synthesis/
│   ├── synthesizer.ts         Merge, deduplicate, rank, cap at 10, summary
│   └── confidence.ts          ReConcile-style weighted consensus calibration
├── github/
│   ├── client.ts              Octokit wrapper: fetch PR, get diff, post review
│   └── formatter.ts           Terminal, markdown, cost report formatters
├── llm/
│   ├── client.ts              LLM SDK client, two-layer caching, retry, cost tracking
│   └── prompts.ts             System prompts for all 5 agents + context builders
├── ui/
│   ├── server.ts              HTTP + SSE server for the web dashboard
│   └── dashboard.html         Single-page dashboard UI
└── lib/
    ├── files.ts               Cached file I/O with LRU
    ├── log.ts                 warn/debug logging utilities
    ├── review-log.ts          JSONL review log writer + reader for crash recovery
    ├── symbols.ts             Shared symbol/regex patterns (7 languages)
    └── math.ts                Entropy, knapsack, TF-IDF, weighted consensus

Development

# Watch mode (recompiles on save)
npm run dev

# One-time build
npm run build

# Run tests
npm test

# Type check without emitting
npm run lint

Planted bugs harness

A test harness with intentionally planted bugs is available for validating the review pipeline without an API key:

# Generate the planted-bugs diff
bash tests/harness/generate-diff.sh

# Dry run against the planted bugs
revue dry-run --file tests/harness/planted-bugs.diff --dump /tmp/revue-prompts

# Inspect what agents would see
ls /tmp/revue-prompts/

Troubleshooting

"Error: ANTHROPIC_API_KEY required"

Set the API key via environment variable or .revuerc:

export ANTHROPIC_API_KEY=sk-ant-api03-...

"Error: GITHUB_TOKEN required"

Only needed for the review command. Set via environment variable:

export GITHUB_TOKEN=ghp_...

"Error: Authentication failed (401)"

Your API key or GitHub token is invalid or expired. Regenerate it and update the environment variable.

"Error: Not found (404)"

Check the --repo format (must be owner/repo) and the PR number. For private repos, ensure your GitHub token has repo scope.

"Error: Network error -- could not reach the remote host"

Check your internet connection. If behind a proxy, configure HTTPS_PROXY.

Rate limiting (HTTP 429)

Revue retries rate-limited requests with exponential backoff (1s, 4s, 16s). If you consistently hit limits, reduce maxConcurrentAgents in your .revuerc:

{
  "maxConcurrentAgents": 2
}

Review crashes mid-run

Use --resume to pick up where it left off:

revue diff --resume .revue/logs/review-2026-03-18T143022.jsonl

"No changes found in diff"

Ensure you have uncommitted changes or that the branch differs from the base. Check git diff main...HEAD manually.

Server errors (HTTP 500, 529)

These are transient API errors. Revue retries automatically up to 3 times. If they persist, the API provider may be experiencing an outage.

High costs

Enable cascade: "enableCascade": true (default)
Use a cheaper model for triage: "triageModel": "claude-haiku-4-5-20251001"
Reduce chunk budget: "chunkTokenBudget": 16000
Run fewer agents: --agents correctness,security
Use revue dry-run first to preview costs before running a real review

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

revue

Table of Contents

Overview

Installation

Quick Start

Supported Models & Providers

Anthropic (Claude)

OpenAI (GPT / o-series)

Google (Gemini)

Provider auto-detection

Commands

revue review

revue diff

revue dry-run

revue ui

Configuration

.revuerc File

Environment Variables

Config Precedence

Full RevueConfig Schema

Review Pipeline

1. Diff Parsing

2. Context Retrieval

3. File Ordering

4. Triage Cascade

5. Knapsack Compression

6. Prompt Caching

7. Specialist Agents

Security Agent

Correctness Agent

Performance Agent

API Contract Agent

Test Coverage Agent

8. Adversarial Debate

9. Synthesis

Web Dashboard

Review Logging & Crash Recovery

Log file location

Event types

Crash recovery with --resume

Cost Control

Typical costs (Anthropic Claude Sonnet)

Output Formats

Terminal (default)

JSON (--json)

GitHub PR Comments (--post)

Incremental Reviews

Test Generation

Project Structure

Development

Planted bugs harness

Troubleshooting

"Error: ANTHROPIC_API_KEY required"

"Error: GITHUB_TOKEN required"

"Error: Authentication failed (401)"

"Error: Not found (404)"

"Error: Network error -- could not reach the remote host"

Rate limiting (HTTP 429)

Review crashes mid-run

"No changes found in diff"

Server errors (HTTP 500, 529)

High costs

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`revue review`

`revue diff`

`revue dry-run`

`revue ui`

Crash recovery with `--resume`

JSON (`--json`)

GitHub PR Comments (`--post`)