Plan Review for Claude Code

Plan twice. Code once. Before Claude executes an implementation plan, an independent AI reviewer — OpenAI Codex or a separate Claude — critiques it in review rounds, and you triage every finding before anything reaches the plan. Reviewing the plan catches design mistakes while they're still cheap to fix — reviewing code is too late.

• Before a plan is approved, the plugin offers an independent review by the reviewer of your choice.
• Every reviewer finding comes to you as a simple choice: Investigate (Claude evaluates it on the merits — and pushes back when it's wrong) or Dismiss (dropped, never raised again); direct reviewer questions ask for your answer.
• Rounds continue automatically until blocking feedback is resolved; you decide when to finish.

Privacy: there is no plan-review-hosted backend. The reviewer CLI you choose sends your plan and review context to that provider under your account; the reviewer's access to your workspace is read-only, and the contents of files it inspects may also be sent to that provider; the plugin's review records stay local in your repo.

Install

You'll need at least one reviewer CLI installed and logged in: codex (OpenAI) and/or claude. Plan Review also requires Bash and Node.js 18+ on PATH; npm is optional and only enables Claude model discovery.

In Claude Code, run:

/plugin marketplace add dachev/plan-review
/plugin install plan-review@plan-review

Start a new session after installing — the plugin's hooks register at session start.

Quick start

There is nothing to learn up front — plan as you normally do:

1. Work in plan mode. When Claude finishes the plan and submits it for approval, expect a red block message first — that is normal: it's how the plugin delivers the review offer, before the approval dialog appears. Claude then presents three options: Review the plan (uses your last successful reviewer, or opens the selector on first use), Review with… (pick reviewer and model from a live, account-aware list when available), or Skip review (straight to the normal approval; you can always review later).

   

2. Pick Review the plan. The first round runs immediately — several quiet minutes is normal. Ctrl+C interrupts only the current reviewer round; review state remains on disk, and the next normal stop retries the round automatically.

3. Triage each finding from the dialogs: Investigate or Dismiss (a direct reviewer question asks for your answer instead). The free-text "Other" field lets you attach guidance. Claude applies sound findings to the plan, disputes unsound ones, and the next round runs when it finishes its turn.

   

4. When all blocking feedback is resolved you'll be offered Continue (keep polishing minor items) or Finish. After completion, Claude summarizes the outcome and returns you to the normal plan-approval dialog.

You can also start a review manually at any time — no plan mode needed:

/plan-review [goal] [--policy minimal|default|strict] [--max-rounds N]
/plan-review resume <review_id>     # continue a parked review
/plan-review ls                     # list reviews and their status

Mid-review you can always ask Claude to pause the review for a longer discussion (no rounds run while paused), or — only if you say so explicitly — abandon it.

Configuration

Preferences live in ~/.claude/plan-review/config.json, managed through the plugin's config CLI — ask Claude to run any of: config list, config get <key>, config set <key> <value>, config unset <key>, config reset. For example:

/plan-review config set reviewer codex
/plan-review config set speak robot
/plan-review config list

Key	Values	Default	What it does
reviewer	codex | claude	first installed CLI	Default reviewer; auto-updated to the last pair you used. Changing the reviewer clears an incompatible stored model.
model	free text	reviewer's CLI default	Checked against the reviewer's live model list; unknown values are accepted with a warning (gateways exist). config set model requires a configured reviewer.
speak	robot | human | ape	human	How findings are worded in triage dialogs: terse-technical, plain conversational, or simplest-possible language.
prompts	on | off	on	Automatic review offers. off = reviews run only via /plan-review; never affects dialogs inside a review you started.

One-off overrides: --reviewer / --model flags when starting a review. Deprecated-but-working aliases (speak <value>, prompts <value>, config --reviewer X --model Y) remain for compatibility.

Recommended for long reviews: Claude Code force-allows a stop after 8 consecutive blocked stops, which caps unattended review rounds. Raise it in ~/.claude/settings.json:

{ "env": { "CLAUDE_CODE_STOP_HOOK_BLOCK_CAP": "1000" } }

Turning offers off

• Durable: /plan-review config set prompts off — no more automatic offers; /plan-review still works.
• Per-session emergency: PLAN_REVIEW_SKIP_PLAN_GATE=1 (plan-approval gate) and PLAN_REVIEW_SKIP_WORKFLOW_GATE=1 (superpowers workflow gate).

Troubleshooting

• No review offer appears — check a reviewer CLI is on PATH, prompts isn't off, and you started a new session after installing. If a review is already active in THIS session, approvals wait for it — /plan-review ls shows it.
• A round seems stuck — rounds are deliberately unbounded; Ctrl+C interrupts the round (state persists and retries on the next stop). For long reviews, raise the block cap (above).
• Model list is empty or unavailable — the reviewer CLI is likely logged out; free-text model entry and the CLI default always work.
• Claude model list unavailable right after install — the discovery dependency installs on first session start (requires npm); reviews still run fine through the claude CLI. Start a new session for the model list.
• node: command not found when a review command runs — the plugin needs Node.js 18+ available on your PATH.

Good to know

• The automatic offer gates fail open: a gate error passes through to normal Claude Code behavior — offers can never hold a plan approval hostage. (Not everything fails open: while a review you started is active, superpowers plan execution is intentionally denied until the review completes or you abandon it, and corrupt review state surfaces as a real error.)

• Superpowers integration: plans written via the superpowers workflow (which skips plan mode) get the same review offer at their execution handoff.

• Review records are plain markdown under .claude/reviews/ (plus a .claude/plan-review/ handoff area) in your workspace — every plan version and reviewer message is inspectable. Plans and reviewer transcripts can be sensitive; unless you intentionally want them in the repo, add to your project's .gitignore:

  .claude/reviews/
  .claude/plan-review/

• Reviews are scoped to your Claude session: concurrent sessions in the same repo review independently, and resuming a session restores its review. A fresh session never inherits another session's review.

• Automatic offers are best-effort. If one does not appear, run /plan-review manually.

Roadmap

• Triage shortcuts (auto-accept/investigate) for more agent autonomy with fewer dialogs
• Expandable per-finding details in triage dialogs (open in browser?)
• More reviewer agents beyond codex/claude; more planner integrations

License

MIT