The Problem It Solves — Why Your Review Loop Falls Apart
You know the pattern: Claude generates a plan, you ask Codex to review it, Claude implements, Codex reviews the code. It's powerful—two models checking each other's work. But without structure, it collapses. The plan drifts between review rounds. Implementation review loses context of the approved plan. Findings get buried in chat. Multiple Claude sessions in the same repository create chaos.
The codex-review plugin, created by developer boyand, fixes this by making the loop repeatable and artifact-driven. It's not a framework or an agent runtime—it's a thin workflow wrapper around two core operations: review the plan, review the implementation. That constraint is its strength.
What It Does — A Structured, On-Disk Workflow
The plugin adds five commands to your Claude Code CLI:
/codex-review:plan– Snapshots the current Claude plan and triggers a Codex review./codex-review:impl– Reviews the implementation against the approvedplan.md./codex-review:summary– Shows severity totals (FIX vs. NO-CHANGE vs. OPEN) and current decisions./codex-review:status– Checks the workflow state./codex-review:doctor– Diagnoses issues (wrong workflow, unresolved session, missing dependencies).
When you run /codex-review:plan, here's what happens:
- The current Claude thread resolves or creates its own workflow directory.
- The current Claude plan is snapshotted into
artifacts/plan.md. - Codex writes a plan review artifact.
- Claude writes findings responses in the same structured flow.
- Claude shows a summary and asks for next steps.
The /codex-review:impl command ensures the implementation is reviewed against the canonical, approved plan. If the workflow is still in the planning phase, it auto-advances.
How To Install And Use It Right Now
Prerequisites:
- Go 1.22+
- Claude Code
- OpenAI Codex CLI (
npm install -g @openai/codex)
Install the plugin:
# From a local checkout
claude plugin add /path/to/codex-review
# Directly from GitHub
claude plugin add github:boyand/codex-review
Workflow Structure:
All workflows live under .claude/codex-review/workflows/<workflow-id>/. Key files include:
workflow.json– State machine.decisions.tsv– Normalized decisions ledger.artifacts/plan.md– The approved, canonical plan.artifacts/plan-review-rN.md– Codex's review for round N.artifacts/plan-findings-rN.md– Claude's responses to findings.artifacts/implement-review-rN.md– Codex's implementation review.artifacts/implement-findings-rN.md– Claude's responses.
Basic Usage Flow:
- In a Claude Code session, develop your initial plan.
- Run
/codex-review:plan deeply review this plan. - Address findings. The approved plan is now locked in
artifacts/plan.md. - Implement the code.
- Run
/codex-review:impl review the implementation deeply. - Codex reviews the code against the frozen plan. No drift.
Why This Matters For Your Daily Work
This plugin directly addresses the chaos of multi-model, multi-round reviews. The approved plan does not drift because every implementation review references the same plan.md artifact. Review history is preserved on disk, not lost in chat. Multiple Claude sessions can operate in the same repository without stepping on each other, as each manages its own loop in its own workflow directory.
It's a minimalist solution: five commands, a clear directory structure, and the discipline to use them. For developers already running Claude-Codex review cycles manually, this eliminates the friction that causes those cycles to break down after one or two rounds.
