# adamsreview

> Multi-stage code review plugin for Claude Code featuring parallel sub-agent detection, automated fix loops, interactive walkthrough, and persistent JSON state.

adamsreview is an open-source Claude Code plugin built by Adam Miller that extends the built-in `/review` command into a six-command multi-stage pipeline. It runs against a regular Claude Code subscription and stores persistent review state under `~/.adams-reviews/` for long-lived review workflows. The project is licensed under MIT and hosted on GitHub.

## What It Is

adamsreview is a code review pipeline plugin for Claude Code that dispatches up to seven parallel sub-agent "lenses" (correctness, security, UX, and others), runs deduplication and validation passes, and produces a structured artifact that downstream commands can act on. The pipeline is modeled after Claude Code's built-in `/review` but extends it with automated fix loops, regression detection, and an interactive walkthrough mode. The author notes, anecdotally, that it catches more real bugs and produces fewer false positives than Claude Code's built-in `/review`, `/ultrareview`, and several third-party tools — though this is self-reported with n=1.

## The Six-Command Pipeline

The plugin ships six namespaced commands that can be used independently or chained:

- **`/adamsreview:review`** — multi-lens review with optional `--ensemble` mode that adds a Codex CLI pass and PR bot-comment scraping on top of internal Claude lenses.
- **`/adamsreview:codex-review`** — Codex CLI peer review with tunable effort levels (`low`, `medium`, `high`, `xhigh`); produces the same artifact shape as `:review`.
- **`/adamsreview:add`** — injects externally-sourced findings (e.g., a cloud `/ultrareview` paste or a teammate's note) into an existing artifact, deduped and validated.
- **`/adamsreview:walkthrough`** — interactive driver for findings that `:fix` would skip; uses Claude Code's `AskUserQuestion` UI to walk through uncertain items one by one and posts a decisions log to the PR.
- **`/adamsreview:fix`** — automated fix loop that dispatches per-fix-group sub-agents in parallel, re-reviews with Opus, reverts regressions, and commits survivors.
- **`/adamsreview:promote`** — human override to promote a single finding to auto-fixable, bypassing the lane filter and score threshold.

## Architecture and State Model

Review state (artifact, trace, phase logs, token logs) is written to `~/.adams-reviews/<repo-slug>/<branch>/<review_id>/`. The artifact schema is defined in `bin/schema-v1.json`. Shared phase fragments live under `fragments/`, helper scripts under `bin/` (auto-added to `$PATH` by the plugin runtime), and command files at bare-stem paths under `commands/`. Python helpers use PEP 723 inline-script shebangs via `uv`, so no venv or global pip install is required — `uv` fetches and caches `jsonschema` on first run.

Token accounting distinguishes sub-agent tokens (precise, per-review, always shown) from orchestrator tokens (opt-in, time-window filtered from Claude Code session transcripts, can over-count if unrelated work happens in the same working directory between review and fix).

## Runtime Dependencies

| Tool | Version | Purpose |
|---|---|---|
| `uv` | 0.7+ | Python helper runner |
| `python3` | 3.10+ | Invoked by `uv` |
| `bash` | 3.2+ | All shell helpers (3.2-portable for macOS default bash) |
| `jq` | 1.6+ | Artifact read helpers |
| `gh` | 2.x | PR comment publish and external scrape |
| `git` | 2.x | Everywhere |

Installation is via the Claude Code plugin marketplace: `/plugin marketplace add adamjgmiller/adamsreview` followed by `/plugin install adamsreview@adamsreview`. Local checkout installs and one-shot `--plugin-dir` launches are also supported.

## Update: v0.4.0

The current release is **v0.4.0**, which introduced the auto-fix-hint feature (Phase 5.5, Phase 7.5, and Step 4.5), enabling `:fix` and `:walkthrough` to batch-accept Sonnet-proposed fixes in a single confirmation step. `/adamsreview:codex-review` landed in v0.3.0. Recent releases have focused on hardening — anti-serialization callouts at fan-out sites, parallel-dispatch correctness, and JSON-pipeline backslash safety. The repository was created in April 2026 and last pushed in May 2026, with active follow-ups tracked in GitHub issues.

## Features
- Multi-lens parallel sub-agent code review (up to 7 lenses)
- Automated fix loop with regression detection and revert
- Interactive walkthrough for uncertain findings via AskUserQuestion UI
- External finding injection with deduplication and validation
- Codex CLI peer review with tunable effort levels
- Ensemble mode combining Claude lenses, Codex CLI, and PR bot-comment scraping
- Persistent JSON artifact state per repo/branch/review
- Auto-fix-hint batch-accept flow for one-confirm fix dispatch
- Per-finding promotion override bypassing lane filter and score threshold
- Token accounting for sub-agent and orchestrator spend
- PR comment publishing and patching via GitHub CLI
- Trivial-mode classifier to skip full lens run on small diffs
- Holistic Opus cross-cutting pass (optional)
- Granular or combined commit modes for fix output

## Integrations
Claude Code, Codex CLI, GitHub CLI (gh), GitHub Pull Requests, Anthropic Claude (Sonnet, Opus), uv (Python runner), jq, Git

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v0.4.0

## Links
- Website: https://github.com/adamjgmiller/adamsreview
- Documentation: https://github.com/adamjgmiller/adamsreview
- Repository: https://github.com/adamjgmiller/adamsreview
- EveryDev.ai: https://www.everydev.ai/tools/adamsreview