Skip to content
Back to search

adamsreview

MarketplaceWorks with Claude CodeGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/adamjgmiller--adamsreview/badge.svg)](/listings/adamjgmiller--adamsreview)

HTML

<a href="/listings/adamjgmiller--adamsreview"><img src="/api/listings/adamjgmiller--adamsreview/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

macOS / Linux

1. 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.) 2. In a Claude Code session: `/plugin marketplace add adamjgmiller/adamsreview` 3. In the same session: `/plugin install adamsreview@adamsreview`

Windows (native)

1. Install [Git for Windows](https://git-scm.com/downloads/win) — 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*). 2. Install [uv](https://docs.astral.sh/uv/), [jq](https://jqlang.github.io/jq/download/), and the [GitHub CLI](https://cli.github.com/). 3. 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:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "adamsreview",
  3. "metadata": {
  4. "description": "Adam Miller's personal Claude Code plugins."
  5. },
  6. "owner": { "name": "Adam Miller" },
  7. "plugins": [
  8. {
  9. "name": "adamsreview",
  10. "source": "./",
  11. "description": "Multi-lens code review pipeline for Claude Code."
  12. }
  13. ]
  14. }
README.md · README · 245 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # adamsreview
  2. 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.
  3. 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.
  4. ```
  5. /plugin marketplace add adamjgmiller/adamsreview
  6. /plugin install adamsreview@adamsreview
  7. ```
  8. The six commands:
  9. - **`/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.
  10. - **`/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`).
  11. - **`/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.
  12. - **`/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.
  13. - **`/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).
  14. - **`/adamsreview:promote`** — human override that promotes a single finding to auto-fixable, bypassing the lane filter and score threshold.
  15. 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.
  16. ## Recommended flow
  17. On a non-trivial PR, the commands work best in this order:
  18. 1. **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`).
  19. 2. **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.
  20. 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.
  21. 4. **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.
  22. 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>/`.
  23. `/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).
  24. ## Documents
  25. - **`CLAUDE.md`** — operational guide for Claude Code sessions working in this repo. Self-contained for routine work; read first on a fresh session.
  26. - **`docs/state-and-gates.md`** — finding state model, score gates, deep/light lanes (the normative spec).
  27. - **`docs/pipeline.md`** — phase trees and token-tally semantics for every command.
  28. - **`docs/helpers.md`** — helper-script inventory and the batched-helper pattern.
  29. - **`bin/schema-v1.json`** — JSON Schema for `artifact.json` (source of truth for artifact shape).
  30. - **`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.
  31. - **`plans/`** — per-branch plan files. Active follow-ups live in GitHub issues; historical backlog at `plans/old-backlog.md` (frozen 2026-05-04).
  32. ## Dependencies
  33. ### Runtime
  34. | Tool | Version | Used by | Notes |
  35. |---|---|---|---|
  36. | `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 |
  37. | `python3` | 3.10+ | invoked by `uv` | `uv` will install a matching Python if needed |
  38. | `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 |
  39. | `jq` | 1.6+ | `artifact-read.sh`, log helpers | `brew install jq` |
  40. | `gh` | 2.x | `artifact-publish.sh`, `external-scrape.sh` | `brew install gh`, `gh auth login` |
  41. | `git` | 2.x | everywhere | standard |
  42. ## Installation
  43. ### macOS / Linux
  44. 1. 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.)
  45. 2. In a Claude Code session: `/plugin marketplace add adamjgmiller/adamsreview`
  46. 3. In the same session: `/plugin install adamsreview@adamsreview`
  47. ### Windows (native)
  48. 1. Install [Git for Windows](https://git-scm.com/downloads/win) — 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*).
  49. 2. Install [uv](https://docs.astral.sh/uv/), [jq](https://jqlang.github.io/jq/download/), and the [GitHub CLI](https://cli.github.com/).
  50. 3. In a Claude Code session: `/plugin marketplace add adamjgmiller/adamsreview` and `/plugin install adamsreview@adamsreview`.
  51. ### Install from a local checkout
  52. 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:
  53. - **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.
  54. - **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.
  55. Both paths still require the runtime deps listed above (`uv`, `jq`, `gh`, `bash`, `git`).
  56. ### Commands (post-install)
  57. All invocations are plugin-namespaced:
  58. - `/adamsreview:review [--ensemble] [--full]`
  59. - `/adamsreview:codex-review [--effort <low|medium|high|xhigh>] [--full]`
  60. - `/adamsreview:add [<paste...>] [--file <path> --line <N> --claim "..."]`
  61. - `/adamsreview:walkthrough [threshold]`
  62. - `/adamsreview:fix [threshold]`
  63. - `/adamsreview:promote <finding_id> [--reason "..."] [--fix-hint "..."]`
  64. `--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.
  65. 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.
  66. ### Plugin-author iteration
  67. 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.
  68. ### Review state location
  69. `/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.
  70. **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.
  71. **Migrating from pre-Stage-2.5 state.** If you have reviews under `~/.claude/reviews/`, either:
  72. ```bash
  73. # Option A: move state to the new canonical root (recommended).
  74. mv ~/.claude/reviews ~/.adams-reviews
  75. # Option B: keep state at the old location via the env var (accepts the prompts).
  76. export ADAMS_REVIEW_REVIEWS_ROOT=~/.claude/reviews
  77. ```
  78. ### Token counts: what they measure
  79. The rendered report can surface two numbers:
  80. - **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.
  81. - **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.
  82. When both are populated they're complementary (no overlap), and together estimate total cost.
  83. #### Orchestrator tokens are opt-in
  84. 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. To avoid pestering users, the helper defaults to skip.
  85. To enable, do **either**:
  86. - **Recommended** — grant your terminal app **Full Disk Access** (System Settings → Privacy & Security → Full Disk Access → `+` your terminal). One toggle, permanent, silences this prompt class for everything launched from your terminal. Then `export ADAMS_REVIEW_TALLY_ORCHESTRATOR=1` in your shell rc (`~/.zshrc`, `~/.bashrc`, etc.) so the helper actually runs.
  87. - **Just opt in without FDA** — `export ADAMS_REVIEW_TALLY_ORCHESTRATOR=1` and accept the macOS prompts when they fire. Each grant survives until the next OS update or terminal-app update; choose this if you want narrower permissions at the cost of clicking *Allow* periodically.
  88. When opted out (the default), the helper exits 0 with one `orchestrator-tally: skipped` line and leaves the artifact's `orchestrator_tokens` field absent. The PR comment shows only **Sub-agent tokens** — still the precise per-review counter and the primary cost signal. Sub-agent tokens log under `~/.adams-reviews/`, which carries no provenance xattr, so that path triggers no prompts.
  89. **Stale-data behavior.** If you opt in for the initial review and then opt out before running `/adamsreview:fix`, the helper preserves the previously-written `orchestrator_tokens` value rather than wiping it. The rendered line shows the last-measured value, not a freshly-skipped zero — meaning it can under-report subsequent fix-time activity. Re-opt-in on the next lifecycle command refreshes. The reverse direction (opt out for review, opt in for fix) has no staleness: the fix-time tally's `--since review_started_at` window covers the full review→fix arc, so the first opt-in write captures everything.
  90. #### Orchestrator tokens can over-count (when opted in)
  91. The transcript scan is a pure time-window filter, so any Claude Code turn in the same working directory between `review_started_at` and the last tally gets counted — even if it's unrelated work. In practice that means:
  92. - **Clean:** review → fix back-to-back, or review → new review on updated codebase (each review's `review_started_at` excludes the prior one's turns).
  93. - **Over-counts:** review → unrelated work in the same cwd → fix (the unrelated turns land in the fix run's re-tally).
  94. - **Mitigation:** run the lifecycle commands close together, or do unrelated work in a different worktree (different cwd → different transcript directory → not scanned).
  95. Sub-agent tokens don't have this problem — their log is per-review. If you need a precise total, trust sub-agent tokens and treat orchestrator tokens as a rough ceiling. See `bin/orchestrator-tokens.sh` header for the full list of caveats.
  96. ### Why `uv` instead of plain pip
  97. PEP 668 (Python 3.12+ with Homebrew) marks system and user site-packages as externally managed and refuses direct `pip install`. The original plan assumed plain pip; `uv`'s inline-script dep spec is the cleanest workaround: each Python helper is self-contained, runs without activation ceremony, and its dep list lives next to the code that imports it. Tradeoff: requires `uv` on the machine running the scripts.
  98. ## Layout
  99. ```
  100. adamsreview/ ← this repo (plugin root)
  101. ├── CLAUDE.md ← operational guide (read first)
  102. ├── README.md ← this file
  103. ├── .claude-plugin/
  104. │ ├── plugin.json ← plugin manifest (name: adamsreview)
  105. │ └── marketplace.json ← single-plugin marketplace
  106. ├── .gitattributes ← LF enforcement
  107. ├── docs/
  108. │ └── archive/ ← frozen historical references (not maintained)
  109. │ ├── README.md ← frozen-as-of banner
  110. │ ├── DESIGN.md ← original normative design (rev 8)
  111. │ └── BUILD.md ← build journal (Stages 1–3 + hardening + walkthrough)
  112. ├── plans/ ← per-branch plan files (umbrella + optional PRD/PLAN/JOURNAL)
  113. ├── test/ ← smoke harness + fixtures
  114. ├── commands/ ← bare-stem command files (plugin namespacing)
  115. │ ├── review.md ← /adamsreview:review
  116. │ ├── codex-review.md ← /adamsreview:codex-review
  117. │ ├── add.md ← /adamsreview:add
  118. │ ├── walkthrough.md ← /adamsreview:walkthrough
  119. │ ├── fix.md ← /adamsreview:fix
  120. │ └── promote.md ← /adamsreview:promote
  121. ├── fragments/ ← shared phase fragments + prompt references
  122. │ ├── _prelude-shared.md ← loaded by every command
  123. │ ├── promote-core.md ← shared precondition + patch (promote + walkthrough)
  124. │ ├── 00-preflight.md … 10-post-fix-and-commit.md
  125. │ │ (incl. 06b-auto-fix-hint.md for Phase 5.5)
  126. │ ├── 02-ensemble-adapter.md ← --ensemble pooling
  127. │ ├── 01-codex-detection.md ← Codex Phase 1 variant
  128. │ ├── 05-codex-validation.md ← Codex Phase 4 variant
  129. │ ├── 06-codex-cross-cutting.md ← Codex Phase 5 variant
  130. │ ├── lens-prompts/ ← per-lens detection prompts
  131. │ └── lens-*-reference.md
  132. ├── bin/ ← helper scripts (plugin runtime auto-adds to $PATH)
  133. │ ├── include ← `!include <fragment>.md` wrapper
  134. │ ├── schema-v1.json ← JSON Schema for artifact.json
  135. │ ├── _common.py ← shared Python helpers
  136. │ ├── artifact-patch.py ← machine-state writer
  137. │ ├── artifact-render.py ← JSON → Markdown
  138. │ ├── artifact-validate.sh ← schema check (bash wrapper)
  139. │ ├── artifact-read.sh ← jq wrapper
  140. │ ├── artifact-publish.sh ← PR comment post/patch
  141. │ ├── artifact-seed.sh ← initial artifact scaffold
  142. │ ├── claude-md-paths.sh ← walk-up CLAUDE.md finder
  143. │ ├── staleness.sh ← git diff intersection
  144. │ ├── freshness-gate.sh ← trace freshness check
  145. │ ├── trivial-check.sh ← trivial-mode classifier
  146. │ ├── codex-poll.sh ← Codex CLI invocation + watchdog
  147. │ ├── parse-validator-result.py ← validator-output parser
  148. │ ├── parse-with-repair.py ← JSON-with-repair parser
  149. │ ├── source-family-map.py ← source-family lookup
  150. │ ├── log-phase.sh ← trace.md + phases.jsonl appender
  151. │ ├── log-tokens.sh ← tokens.jsonl appender
  152. │ └── (other helpers: group-fixes.py, repo-slug.sh, comment-freshness.sh,
  153. │ origin-crosscheck.sh, prior-fix-diff.sh, external-scrape.sh,
  154. │ assign-finding-ids.sh, line-range-check.sh, tally-subagent-tokens.sh,
  155. │ orchestrator-tokens.sh)
  156. ├── hooks/
  157. │ ├── hooks.json ← SessionStart registration
  158. │ └── dep-check.sh ← soft dep-missing warning at session start
  159. └── scripts/
  160. └── dev-run.sh ← `claude --plugin-dir` wrapper (plugin-author iteration)
  161. ```
  162. No symlinks, no install script. The plugin runtime discovers `commands/`, `fragments/`, `bin/`, and `hooks/` by convention once the plugin is installed via `/plugin install adamsreview@adamsreview`.
  163. ## Troubleshooting
  164. ### First invocation is slow
  165. The Python helpers (`artifact-patch.py`, `artifact-render.py`) use a PEP 723 inline-script shebang (`#!/usr/bin/env -S uv run --quiet --script`). On a fresh machine, the first run pauses for a few seconds while `uv` resolves a matching Python interpreter and fetches the `jsonschema` dep into its cache. Subsequent runs hit the cache and are effectively instant. This is a one-time cost per machine, not per review.
  166. ### `--ensemble` mode requirements
  167. `/adamsreview:review --ensemble` additionally requires the `codex` Claude Code plugin (the local Codex CLI is invoked through the plugin's `codex-companion.mjs`, not as a standalone CLI on `$PATH`). Without the plugin installed, the readiness gate prompts you to either continue without Codex (in PR mode that means PR-comment scraping only; in local mode it means internal lenses only — Phase 1.5 has no work to do) or stop and run `/codex:setup` first. The default (non-ensemble) mode has no such requirement.
  168. ### Windows: Git Bash not found
  169. Claude Code auto-discovers Git Bash on Windows and routes `#!/usr/bin/env bash` helpers through it. If the auto-discovery fails (non-default Git Bash install path, portable install, etc.), set `CLAUDE_CODE_GIT_BASH_PATH` to the absolute path of `bash.exe` before launching Claude Code — for example:
  170. ```
  171. set CLAUDE_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe
  172. ```
  173. or the `$env:CLAUDE_CODE_GIT_BASH_PATH = ...` equivalent in PowerShell.
  174. ## Status
  175. Current release: **v0.4.0** (auto-fix-hint feature: Phase 5.5 + Phase 7.5 + Step 4.5). All six commands are shipped and in daily use. `/adamsreview:codex-review` landed in v0.3.0; recent releases have focused on hardening (anti-serialization callouts at fan-out sites, parallel-dispatch correctness, JSON-pipeline backslash safety) and the auto-fix-hint flow that lets `:fix` and `:walkthrough` batch-accept Sonnet-proposed fixes in one confirm.
  176. Active follow-ups live in GitHub issues. Frozen historical context: `plans/old-backlog.md` and `docs/archive/`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.