The Technique — A Thin Workflow for Two Models
Developers have long known that combining Claude's planning strength with Codex's sharp review capabilities yields high-quality results. The problem is maintaining that loop. Without structure, plans drift between review rounds, implementation reviews lose the original context, and findings discussed in chat disappear. The codex-review plugin for Claude Code solves this by enforcing a simple, repeatable workflow with just five commands.
It's not a framework or an agent runtime. It's a thin wrapper around two core operations: /codex-review:plan and /codex-review:impl. This constraint is its strength, creating a canonical, on-disk record of the entire review process that any Claude session in the repo can follow.
Why It Works — Artifacts Over Chat
The plugin works by creating and managing a set of immutable artifacts in a .claude/codex-review/workflows/<workflow-id>/ directory. This is the key to solving the collaboration problem.
When you run /codex-review:plan, it snapshots the current Claude plan into artifacts/plan.md. Codex then reviews this plan, writing its feedback to artifacts/plan-review-rN.md. Claude responds to findings in artifacts/plan-findings-rN.md. A decisions.tsv file acts as a ledger. This ensures the "approved plan" is a specific file on disk, not a vague memory in a chat thread.
Subsequent /codex-review:impl commands review the current code against that canonical plan.md. The history of all review rounds is preserved on disk, preventing context loss and allowing multiple developers (or multiple Claude sessions) to work in the same repository without stepping on each other's workflows.
How To Apply It — Setup and Commands
First, ensure you have the prerequisites:
- Go 1.22+
- Claude Code
- OpenAI Codex CLI (
npm install -g @openai/codex)
Install the plugin directly from GitHub:
claude plugin add github:boyand/codex-review
Now, integrate it into your development loop:
- Plan with Claude. In your Claude Code session, develop a plan for a feature or fix.
- Review the Plan. Run
/codex-review:plan deeply review this plan. This kicks off the artifact creation and Codex review cycle. Claude will show a summary and ask for next steps. - Implement. Have Claude write the code based on the now-approved
plan.md. - Review the Implementation. Run
/codex-review:impl review the implementation deeply. Codex will check the code against the saved plan.
Use the supporting commands to manage the workflow:
/codex-review:summary: See severity totals (FIX vs. NO-CHANGE vs. OPEN) and what the current round decided./codex-review:status: Check the workflow's current state./codex-review:doctor: Diagnose issues like missing Codex CLI or unresolved Claude sessions.
This creates a disciplined, audit-ready development process where the model's strengths are systematically leveraged and every decision is recorded.
