Code Reviewer

A CI-native AI code review runner for GitHub and GitLab. Install it once, trigger it from pull/merge request CI, and configure each repo with a small .ai-review.json. You never fork the core.

Deterministic code owns the boring, safety-critical parts (fetching diffs, filtering, risk tiering, timeouts, retries, state, publishing, the CI gate). LLM agents handle the judgment: specialist reviewers fan out by risk and domain, a coordinator fuses their findings. The CI status is the merge gate; comments are just the human-facing UX.

Project status

This is a working prototype, not a finished product. It runs real reviews today (GitHub and GitLab adapters, Pi-backed models, CI templates, summary publishing, incremental re-review). Two things to know before you install:

• Published to npm. Install with bun add @briggsd/code-reviewer (bun-native; requires Bun). For internal CI or air-gapped environments, pin AI_REVIEW_PACKAGE to an immutable tarball or exact package version instead of a mutable branch or latest.
• Bun is required to run it. The CLI runs TypeScript directly through Bun with no build step, so any environment that runs the bin needs Bun >=1.3.0.

Try it in 30 seconds

No tokens, no model API key. Clone, install, run the bundled fixture through the deterministic dummy runtime:

git clone https://github.com/briggsd/code-reviewer.git
cd code-reviewer
bun install
bun run src/cli.ts run --fixture examples/fixtures/auth-pr.json --runtime dummy --format markdown

You get a full review summary, including a planted critical finding:

## AI review found significant concerns

🔴 Significant concerns — Risk tier `full` · CI `fail`

Files reviewed: 1 · Findings: 1

### 🔒 security — 🔴 1 critical
- CRITICAL: Account lookup misses authorization (auth/accounts.ts:23)
  Why it matters: the lookup uses a request-supplied accountId without proving the
  caller can access that account.

The dummy runtime is deterministic and needs no model, so this is a demo of the pipeline, not a real model review. To point it at your own edits, change some files in this repo and run:

bun run review:local   # reviews your uncommitted git diff with the dummy runtime

It reads the working-tree diff, so a clean checkout reviews nothing. Run git add -N <path> first if you want brand-new untracked files included.

For a real model-backed review of your working-tree diff, run:

bun run review   # = run --git-diff --runtime pi; needs a provider key (e.g. ANTHROPIC_API_KEY) or stored pi OAuth

To point any run at a real model, pass --model <provider>/<model> — this auto-selects the Pi runtime, and --api-key takes a literal key or env:NAME:

bun run src/cli.ts run --fixture examples/fixtures/auth-pr.json \
  --model anthropic/claude-sonnet-4-6 --api-key env:ANTHROPIC_API_KEY

Install it in another repo's CI

The real use is running on every PR/MR. The short version:

1. Pin an install source. CI installs the runner with bun add --global "$AI_REVIEW_PACKAGE". Point AI_REVIEW_PACKAGE at an immutable source (a pinned commit or an internal tarball); do not use main, a branch, or latest.
2. Add .ai-review.json at the repo root. Start in advisory mode so reviews run without blocking merges while you calibrate.
3. Copy a CI template from examples/ci/ and keep the runtime on dummy until install, fetch, and artifact upload all work. Then switch trusted jobs to pi.
4. Keep fork jobs read-only (no secrets, no write token, no publish).

Full walkthrough with the two-job CI shape and the smoke-PR checklist: Getting started.

Configure

A minimal .ai-review.json:

{
  "mode": "advisory"
}

Switch to a merge gate when you trust the reviews:

{
  "mode": "blocking",
  "failOn": ["critical"]
}

Config arrays replace the built-in defaults rather than merging, so read Configuration before overriding sensitivePaths, reviewer policy, or model routing. Regenerate the published JSON schema with bun run schema:config.

How it works

PR/MR event
  -> CI job runs code-reviewer
  -> VCS adapter fetches metadata + diff + prior review state
  -> diff filter -> risk classifier (trivial / lite / full)
  -> shared context -> coordinator -> specialist reviewer fan-out -> coordinator fusion
  -> publisher writes summary + CI status -> traces/state persisted

Risk tier decides how much review a change gets: small diffs run cheap, risky ones pull in more reviewers and stronger models. Re-pushes carry prior state forward, so later rounds classify findings as new, recurring, fixed, or withheld instead of re-reviewing from scratch. See How it works and, for the full design, Architecture.

Safety

All PR/MR content (titles, descriptions, comments, diffs, repo files) is treated as untrusted and sanitized before it reaches a prompt. Only factory-owned reviewer definitions run; reviewed-repo Pi/project resources stay disabled in CI. Fork PRs never get secrets or a write token by default. See Fork safety and Security policy (report vulnerabilities privately).

Documentation

Adopters

• Getting started — install, configure, wire CI, smoke-test a PR/MR.
• How it works — adopter lifecycle, gate policy, reviewer/model routing.
• Adoption guide — operator checklist, live-tested evidence, rollout.
• Configuration — .ai-review.json fields, merge behavior, schema.
• CI templates — GitHub Actions and GitLab CI starters.
• GitHub Action wrapper — thin uses: wrapper.
• Fork safety — fork strategy and secret/write-token boundaries.
• Inline publishing — experimental GitHub inline comments.
• Internal/self-managed GitLab beta onboarding — self-managed setup and tokens.

Packaging & release

• Packaging · Release artifacts · Release readiness
• Smoke tests: Workflow · Pi live · GitLab live smoke

Design & internals

• Architecture — system design, lifecycle, security model.
• Extending and testing — integration recipes + test-infra index.
• Decision guardrails — load-bearing invariants.
• Reviewer conventions · Operator-extension seam · Re-review state
• Telemetry export · Evals · Runtime comparison

Development

Bun >=1.3.0, TypeScript, no build step. Tests are fake and offline by default.

bun run gate     # full pre-PR gate (tsc + tests + boundaries + lint + docs + complexity + knip)
bun run check    # the tsc + test core
bun test         # bun:test suite

Packaging and opt-in live smokes (network/model-gated, off by default):

bun run pack:smoke              # validate the npm tarball contents + packaged CLI
bun run smoke:external-package  # install the tarball into an isolated Bun dir, run code-reviewer
bun run smoke:gitlab            # live GitLab MR smoke (needs AI_REVIEW_LIVE_GITLAB=1)

Run bun run src/cli.ts run --help for the full CLI surface (provider fetches, summary/inline publishing, runtime selection). Contribution guidelines and the security policy are in CONTRIBUTING.md and SECURITY.md.

License

Apache-2.0.