branch-review

Orchestrate multi-agent code reviews from CLI or dashboard

What It Does

branch-review coordinates code review agents and static analysis tools into a unified workflow. Run reviews from the CLI with reviewctl, or manage them visually through the web dashboard.

Two interfaces:

• reviewctl CLI - Orchestrate reviews from terminal
• Web Dashboard - Visual review management at localhost:3000

Features

• 9 CLI commands for complete review workflow
• Multi-agent support (code-reviewer, code-simplifier, sql-safety-hunter)
• Static analysis integration (biome, ruff, pyrefly)
• Diff-based review scope for branches and isolated worktrees
• Scoped static-gate requests with explicit applicability states (PENDING, PENDING_NO_CONFIG, SKIP, NOT_APPLICABLE)
• Plan-based reviews with drift detection
• Priority findings: P0 (blocking), P1 (important), P2 (minor)
• Real-time dashboard with verdict visualization
• Post-PR learning hook that extracts reusable decision skills into skills/learned/

Quick Start

bun install           # Install dependencies
bun run dev           # Start dashboard at localhost:3000
bun reviewctl help    # Show CLI commands

Quality Checks

bun run lint                                                # ESLint repo gate
BR_BIOME_SINCE=origin/main bash scripts/run-biome-check.sh # Biome CLI on changed JS/TS/JSON
BR_DIFF_RANGE=origin/main...HEAD bash scripts/run-ruff-check.sh # Ruff on changed Python files
bun run audit:deps                                        # Dependency vulnerability audit

run-biome-check.sh uses Biome CLI (biome check --changed --since=<ref>) and validates the --since ref before execution.

CLI Commands

Command	Purpose
init	Create review run on review/* branch
explore context	Gather repository context
explore diff	Analyze branch changes
plan	Generate review plan
run	Create handoff requests for agents
ingest --agent <name>	Capture agent output
status	Show run progress and status
verdict	Generate final PASS/FAIL verdict
merge	Merge branch after PASS
cleanup	Remove run artifacts

Command Details

init - Initialize review run

reviewctl init --create --base main --target feat/my-feature
reviewctl init --create                              # base=auto, target=HEAD
reviewctl init --branch feat/x                       # deprecated, use --target

status - Show run status

reviewctl status              # current active run
reviewctl status --last       # most recent run
reviewctl status --run-id run_20260227_abc123
reviewctl status --json       # JSON output

run - Generate agent handoffs

reviewctl run                         # fail if drift detected
reviewctl run --allow-drift           # override drift (debug only)
reviewctl run --max-agents 2

Notes:

• reviewctl evaluates branch diff / worktree diff scope, not ad-hoc file lists.
• ruff should be executed diff-scoped via BR_DIFF_RANGE=<base>...HEAD bash scripts/run-ruff-check.sh.
• pytest should not default to repo-wide execution for isolated worktrees when no scoped Python test target exists.

ingest - Capture agent/static output

reviewctl ingest --agent code-reviewer --input report.md
reviewctl ingest --static ruff --input ruff-output.txt

Workflow

init → explore context → explore diff → plan → run → ingest → verdict → merge

API Endpoints

Method	Endpoint	Returns
GET	/api/review/info	API metadata (public)
GET	/api/review/run	Current run status
POST	/api/review/command	Execute reviewctl command
GET	/api/review/final	Final verdict JSON
GET	/api/review/state	Run state snapshot

Tech Stack

Layer	Technology
Runtime	Bun
Framework	Next.js 16 (App Router)
Language	TypeScript 5
Styling	Tailwind CSS 4 + shadcn/ui
State	Zustand + TanStack Query
CLI	Commander + Chalk
Database	Prisma
Auth	NextAuth.js
Validation	Zod + React Hook Form

Project Structure

src/
├── app/
│   ├── api/review/      # REST endpoints
│   └── page.tsx         # Dashboard UI
├── components/ui/       # shadcn/ui components
└── lib/                 # Services and utilities

mini-services/reviewctl/
└── src/
    ├── index.ts         # CLI entry
    ├── commands/        # Command handlers
    └── lib/             # CLI utilities

PM2 Deployment

Run the API as a daemon with PM2:

# 1. Create .env with your token
echo "REVIEW_API_TOKEN=your-secure-token-here" > .env

# 2. Build production bundle
bun run build

# 3. Start with PM2
pm2 start ecosystem.config.js

# 4. Save PM2 configuration
pm2 save

API will be available at: http://localhost:3001

Authentication: /api/review/info is public. Other /api/review/* endpoints require X-Review-Token header or review_api_token cookie.

See docs/agent-task-card.md for full API documentation.

Contributing

Read these before submitting PRs:

• docs/operating-rules.md
• docs/cli-flow.md
• docs/pr-dod.md

License

MIT