GitHub - adamjgmiller/adamsreview: Multi-lens code review pipeline for Claude Code: deep review (Claude or Codex), auto-fix loop, interactive walkthrough, external-finding injection.

Multi-stage code review for Claude Code — parallel sub-agent detection, validation passes, persistent JSON state, and an automated fix loop that re-reviews and reverts regressions before committing. On my own PRs, it's been catching dramatically more real bugs than Claude Code's built-in /review, /ultrareview, CodeRabbit, Greptile, and Codex's built-in review — while producing fewer false positives. (Anecdotal, n=me.) Modeled after the built-in /review and extended into a six-command pipeline. Runs against your regular Claude Code subscription (Max plan recommended) — unlike /ultrareview, which charges against your Extra Usage pool. /plugin marketplace add adamjgmiller/adamsreview /plugin install adamsreview@adamsreview

The six commands:

/adamsreview:review — multi-lens code review of a branch or PR. Up to seven parallel sub-agent lenses (correctness, security, UX, etc.) feed a dedup pass, a cheap-then-deep validation gate, and (optionally) a holistic Opus cross-cutting pass. High-confidence auto-fix proposals are pre-computed so :fix and :walkthrough can batch-accept them in one confirm. --ensemble adds a Codex CLI pass and PR bot-comment scrape on top of the internal Claude lenses. /adamsreview:codex-review — Codex CLI peer to :review. Same artifact shape, drop-in for everything downstream (:fix, :add, :walkthrough, :promote). Effort tunable via --effort low|medium|high|xhigh (default high). /adamsreview:add — inject externally-sourced findings (a Claude Code cloud /ultrareview paste, an Opus once-over, a teammate's note) into the most recent review's artifact. Deduped against what's already there, validated by the same gates, re-published to the existing PR comment. /adamsreview:walkthrough — interactive driver for findings :fix would skip. Uses the harness's AskUserQuestion UI to walk through uncertain or human-judgment items one by one — promote what you want auto-fixed, skip the rest. Pre-computed auto-fix proposals are batch-accepted up front; the remainder get per-finding briefing + options + recommendation. Posts a decisions log to the PR. /adamsreview:fix — automated fix loop.

Dispatches per-fix-group sub-agents in parallel, then re-reviews the work with Opus, reverts any regressions, and commits the survivors (one combined commit by default; --granular-commits for one per group). /adamsreview:promote — human override that promotes a single finding to auto-fixable, bypassing the lane filter and score threshold.

Command files live at bare-stem paths under commands/; shared phase fragments and prompt references live under fragments/; helper scripts and the artifact schema live under bin/. The plugin runtime auto-adds bin/ to $PATH on load — no symlinks, no install script. Recommended flow On a non-trivial PR, the commands work best in this order:

Review. /adamsreview:review — or /adamsreview:review --ensemble if you have the Codex CLI installed and want to pool a Codex pass plus a PR bot-comment scrape on top of the internal Claude lenses (higher token cost). Or /adamsreview:codex-review [--effort <level>] for a Codex-driven peer review (drop-in for everything downstream; effort tunable; no --ensemble). Add. (optional) /adamsreview:add <paste...> — if you ran a parallel review (cloud /ultrareview, Opus once-over, manual scan, etc.) that surfaced bugs the original review missed, paste the result here. The findings are validated by Phase 4 and land in the same artifact, deduped against what's already there. Auto-eligible additions feed step 4; non-eligible ones surface in step 3. Walkthrough. (optional) /adamsreview:walkthrough [threshold] — step through findings the fix command would skip (deep-manual, deep-report, and the entire light lane including light confirmed_mechanical), restricted to those scoring at or above $threshold (default 60) so low-signal items don't pad the session. Step 4.5 batch-accepts all findings carrying a pre-computed auto-fix proposal in one confirm (the fast path); the rest get per-finding briefing + options + recommendation via the harness's AskUserQuestion UI. Promote the ones you want auto-fixed with tailored fix-hints, skip the rest. Posts a decisions log to the PR for audit.

Pass a lower threshold (e.g. /adamsreview:walkthrough 30) and pick the Full tier at the preflight prompt to audit Phase-3-demoted below_gate findings too. Fix. /adamsreview:fix — applies every auto-eligible finding (including whatever was added in step 2 and promoted in step 3). Phase 7.5 surfaces any remaining auto-fix proposals (light-lane / manual / report findings) for one-confirm batch-accept before Phase 8 dispatch. Default: one combined commit for all surviving fixes; pass --granular-commits for one commit per fix group. Per-group Phase-9 outcome lands in the commit message either way.

Each command is independent — you can go straight from review to fix if you only care about auto-eligible findings, or skip review entirely and run :fix against an existing artifact. Steps 2–4 can land days or weeks after step 1; the review artifact persists under ~/.adams-reviews/<slug>/<branch>/. /adamsreview:promote <id> remains useful for one-off manual promotions outside the walkthrough flow (e.g. promoting a disproven finding with --force, or conceptually looping over a set of IDs — F003, F037, F039 — with --defer-publish on each so only the final invocation re-publishes to the PR). Documents

CLAUDE.md — operational guide for Claude Code sessions working in this repo. Self-contained for routine work; read first on a fresh session. docs/state-and-gates.md — finding state model, score gates, deep/light lanes (the normative spec). docs/pipeline.md — phase trees and token-tally semantics for every command. docs/helpers.md — helper-script inventory and the batched-helper pattern. bin/schema-v1.json — JSON Schema for artifact.json (source of truth for artifact shape). docs/archive/ — frozen design + build docs (2026-04-19 onward). DESIGN.md (rev 8) is the original normative spec; BUILD.md is the stage-by-stage journal. Not maintained; consult only for historical rationale. plans/ — per-branch plan files. Active follow-ups live in GitHub issues; historical backlog at plans/old-backlog.md (frozen 2026-05-04).

Dependencies Runtime

Tool Version Used by Notes

uv 0.7+ artifact-patch.py, artifact-render.py brew install uv. Scripts use a PEP 723 inline-script shebang (#!/usr/bin/env -S uv run --quiet --script) so uv fetches and caches jsonschema on first run — no venv, no global pip install

python3 3.10+ invoked by uv uv will install a matching Python if needed

bash 3.2+ all *.sh helpers Helpers are intentionally 3.2-portable (no declare -A, mapfile, ${var,,}), so macOS's default /bin/bash works as-is. On Windows, Git for Windows ships bash 5+ via Git Bash and Claude Code auto-routes through it

jq 1.6+ artifact-read.sh, log helpers brew install jq

gh 2.x artifact-publish.sh, external-scrape.sh brew install gh, gh auth login

git 2.x everywhere standard

Installation macOS / Linux

Install deps: brew install uv jq gh git (macOS) or the distro equivalent. (macOS's default /bin/bash 3.2 is fine — helpers are 3.2-portable.) In a Claude Code session: /plugin marketplace add adamjgmiller/adamsreview In the same session: /plugin install adamsreview@adamsreview

Windows (native)

Install Git for Windows — provides Git Bash (bash 5+) and git, which Claude Code uses internally. Claude Code auto-routes #!/usr/bin/env bash helpers through Git Bash; set CLAUDE_CODE_GIT_BASH_PATH if Git Bash lives in a non-default location (see Troubleshooting). Install uv, jq, and the GitHub CLI. In a Claude Code session: /plugin marketplace add adamjgmiller/adamsreview and /plugin install adamsreview@adamsreview.

Install from a local checkout If you've cloned this repo and prefer running from source — or you want to pin to a specific commit — two paths work without the GitHub marketplace round-trip:

Persistent install from a local path. In a Claude Code session, run /plugin marketplace add /path/to/adamsreview then /plugin install adamsreview@adamsreview.

Same end state as the GitHub marketplace flow above — the plugin is registered under ~/.claude/ and survives restarts. Use . in place of the absolute path if your cwd is already the clone. One-shot via --plugin-dir. claude --plugin-dir /path/to/adamsreview launches Claude Code with the clone loaded as a plugin for that session only. Nothing is written to ~/.claude/; re-launch without the flag and the plugin is gone. Handy for trying the plugin without any persistent state, or for running a specific checkout side-by-side with an installed version.

Both paths still require the runtime deps listed above (uv, jq, gh, bash, git). Commands (post-install) All invocations are plugin-namespaced:

/adamsreview:review [--ensemble] [--full] /adamsreview:codex-review [--effort <low|medium|high|xhigh>] [--full] /adamsreview:add [<paste...>] [--file <path> --line <N> --claim "..."] /adamsreview:walkthrough [threshold] /adamsreview:fix [threshold] /adamsreview:promote <finding_id> [--reason "..."] [--fix-hint "..."]

--full (on :review and :codex-review) opts out of the trivial-mode optimization, forcing every detection lens to run even on small or docs-only diffs. Useful when you want full coverage on a deliberately-small PR; otherwise the default trivial-mode classifier is the right call. No separate Python dep install. First invocation of any *.py helper triggers uv to resolve declared deps (jsonschema etc.) and cache them — this can take a few seconds on a fresh machine (see Troubleshooting). Subsequent runs are fast. Plugin-author iteration If you're hacking on the plugin itself (not just using it), scripts/dev-run.sh launches Claude Code with the working tree loaded as a plugin via claude --plugin-dir "$(pwd)" — no marketplace install needed. For install-path simulation from a working tree, run /plugin marketplace add .

inside a Claude Code session. Review state location /adamsreview:review writes per-run state (artifact, trace, phase logs, token logs) under ~/.adams-reviews/<repo-slug>/<branch>/<review_id>/. Override with export ADAMS_REVIEW_REVIEWS_ROOT=/some/other/path if you want state elsewhere. Why not ~/.claude/reviews/? Claude Code hardcodes a sensitive-file permission prompt for writes to ~/.claude/... that survives even bypassPermissions mode, and ~/.claude/reviews is not on the short list of exempt subdirs (.claude/commands, .claude/agents, .claude/skills). Keeping review state outside ~/.claude/ avoids dozens of permission prompts per run. Migrating from pre-Stage-2.5 state. If you have reviews under ~/.claude/reviews/, either: # Option A: move state to the new canonical root (recommended). mv ~/.claude/reviews ~/.adams-reviews

# Option B: keep state at the old location via the env var (accepts the prompts). export ADAMS_REVIEW_REVIEWS_ROOT=~/.claude/reviews Token counts: what they measure The rendered report can surface two numbers:

Sub-agent tokens — rolled up from the per-review tokens.jsonl log. Counts every dispatched sub-agent (lenses, validators, fix agents, post-fix reviewer, etc.) for this specific review. Precise. Always shown. Orchestrator tokens — rolled up from the Claude Code session transcripts under ~/.claude/projects/<cwd-slug>/, filtered to assistant turns with timestamp >= review_started_at. Captures the main-session spend that subagent_tokens deliberately excludes. Opt-in — see below.

When both are populated they're complementary (no overlap), and together estimate total cost. Orchestrator tokens are opt-in macOS Sequoia and Tahoe show an "kitty (or your terminal) would like to access data from other apps" prompt the first time a shell helper reads files marked with the com.apple.provenance extended attribute. Every Claude Code transcript carries one, and bin/orchestrator-tokens.sh reads them — so the helper would trigger the prompt on the first lifecycle command of every review and (because the TCC cache for this gate is partial) repeatedly thereafter.