| name | codex-review |
|---|---|
| description | Send the current plan or uncommitted code changes to OpenAI Codex CLI for iterative review. Claude and Codex go back-and-forth until Codex approves. Max 5 rounds. In code-review mode, after approval auto-commits and merges the feature branch into main (no push). |
| user_invocable | true |
Send the current implementation plan or uncommitted code changes to OpenAI Codex for review. Claude revises based on Codex's feedback and re-submits until Codex approves. Max 5 rounds.
On code-review approval, automatically stage+commit the reviewed changes and merge the feature branch back into main (local only — never pushes).
- When the user runs
/codex-reviewduring or after plan mode (plan review) - When the user runs
/codex-reviewafter implementing code changes (code review) - When the user wants a second opinion from a different model
When invoked, perform the following iterative review loop:
Generate a unique ID to avoid conflicts with other concurrent Claude Code sessions:
REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)Use this for all temp file paths: /tmp/claude-review-${REVIEW_ID}.md and /tmp/codex-review-${REVIEW_ID}.md.
Determine what to review based on context:
Mode A — Plan Review (if a plan exists in the current conversation context):
- Write the full plan content to
/tmp/claude-review-${REVIEW_ID}.md - Set
REVIEW_MODE=plan
Mode B — Code Review (if no plan, but uncommitted changes exist):
- Run
git diffandgit diff --cachedto capture all staged and unstaged changes - Write the combined diff output to
/tmp/claude-review-${REVIEW_ID}.md - Set
REVIEW_MODE=code
No content: If there is no plan in context AND no uncommitted changes, ask the user what they want reviewed.
Tell the user which mode was detected: "Detected plan review mode" or "Detected code review mode — reviewing uncommitted changes".
Run Codex CLI in non-interactive mode. The review prompt differs by mode:
For Plan Review (REVIEW_MODE=plan):
codex exec \
-m gpt-5.3-codex \
-s read-only \
-o /tmp/codex-review-${REVIEW_ID}.md \
"Review the implementation plan in /tmp/claude-review-${REVIEW_ID}.md. Focus on:
1. Correctness - Will this plan achieve the stated goals?
2. Risks - What could go wrong? Edge cases? Data loss?
3. Missing steps - Is anything forgotten?
4. Alternatives - Is there a simpler or better approach?
5. Security - Any security concerns?
Be specific and actionable. If the plan is solid and ready to implement, end your review with exactly: VERDICT: APPROVED
If changes are needed, end with exactly: VERDICT: REVISE"For Code Review (REVIEW_MODE=code):
codex exec \
-m gpt-5.3-codex \
-s read-only \
-o /tmp/codex-review-${REVIEW_ID}.md \
"Review the code changes (git diff) in /tmp/claude-review-${REVIEW_ID}.md. Also read the relevant source files in the repo for full context. Focus on:
1. Correctness / bug risk - Will this code work as intended?
2. Regression risk - Could this break existing functionality?
3. Edge cases - Are boundary conditions handled?
4. Security - Any security vulnerabilities introduced?
Classify each issue as:
- BLOCKING: Must fix before merge (bugs, security, data loss risk)
- NON_BLOCKING: Improvement suggestions (can be addressed later)
Report only real problems. Skip style nitpicks unless they could cause bugs.
If the code is solid and ready to merge, end your review with exactly: VERDICT: APPROVED
If changes are needed, end with exactly: VERDICT: REVISE"Capture the Codex session ID from the output line that says session id: <uuid>. Store this as CODEX_SESSION_ID. You MUST use this exact ID to resume in subsequent rounds (do NOT use --last, which would grab the wrong session if multiple reviews are running concurrently).
Notes:
- Use
-m gpt-5.3-codexas the default model. If the user specifies a different model (e.g.,/codex-review o4-mini), use that instead. - Use
-s read-onlyso Codex can read the codebase for context but cannot modify anything. - Use
-oto capture the output to a file for reliable reading.
- Read
/tmp/codex-review-${REVIEW_ID}.md - Present Codex's review to the user:
## Codex Review — Round N [Plan|Code] (model: gpt-5.3-codex)
[Codex's feedback here]
- Check the verdict:
- If VERDICT: APPROVED → go to Step 7 (Done)
- If VERDICT: REVISE → go to Step 5 (Revise & Re-submit)
- If no clear verdict but feedback is all positive / no actionable items → treat as approved
- If max rounds (5) reached → go to Step 7 with a note that max rounds hit
Based on Codex's feedback, the revision approach differs by mode:
Plan Review: Revise the plan — address each issue Codex raised. Update the plan in conversation context and rewrite /tmp/claude-review-${REVIEW_ID}.md.
Code Review: Fix the code — apply changes to the actual source files using Edit tool to address BLOCKING issues. Then regenerate the diff and rewrite /tmp/claude-review-${REVIEW_ID}.md with the updated diff.
In both modes, briefly summarize what was changed:
### Revisions (Round N)
- [What was changed and why, one bullet per Codex issue addressed]
Inform the user: "Sending revised [plan|code] back to Codex for re-review..."
Resume the existing Codex session so it has full context of the prior review:
codex exec resume ${CODEX_SESSION_ID} \
"I've revised the [plan|code] based on your feedback. The updated content is in /tmp/claude-review-${REVIEW_ID}.md.
Here's what I changed:
[List the specific changes made]
Please re-review. If it's now solid, end with: VERDICT: APPROVED
If more changes are needed, end with: VERDICT: REVISE" 2>&1 | tail -80Note: codex exec resume does NOT support -o flag. Capture output from stdout instead (pipe through tail to skip startup lines). Read the Codex response directly from the command output.
Then go back to Step 4 (Read Review & Check Verdict).
Important: If resume ${CODEX_SESSION_ID} fails (e.g., session expired), fall back to a fresh codex exec call with context about the prior rounds included in the prompt.
Once approved (or max rounds reached):
## Codex Review — Final [Plan|Code] (model: gpt-5.3-codex)
**Status:** Approved after N round(s)
[Final Codex feedback / approval message]
---
**[Plan|Code] has been reviewed and approved by Codex.**
If max rounds were reached without approval:
## Codex Review — Final [Plan|Code] (model: gpt-5.3-codex)
**Status:** Max rounds (5) reached — not fully approved
**Remaining concerns:**
[List unresolved issues from last review]
---
**Codex still has concerns. Review the remaining items and decide whether to proceed.**
This step runs only when all of the following are true:
REVIEW_MODE=code- Codex verdict is APPROVED (or max-rounds reached with code already fixed — treat max-rounds as NOT approved, skip auto-merge)
- The user has NOT said "review only" / "don't commit" / "don't merge" in the current invocation
Skip this step silently for plan-review mode.
Substep 8a — Generate commit message
Claude writes a 1–2 line imperative commit message from the diff it already reviewed. Format:
<short imperative subject, under 70 chars>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Do not mention the review process in the subject — describe the code change itself.
Substep 8b — Stage and commit in the current worktree
Stage only files that appeared in the reviewed diff (do NOT git add -A or .). Commit with the message from 8a.
# From the current worktree (where the changes are)
git add <files-from-diff>
git commit -m "$(cat <<'EOF'
<subject>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF
)"If the pre-commit hook fails: report the failure to the user and stop. Do NOT use --no-verify. Do NOT amend. The user fixes the hook issue and re-invokes.
Substep 8c — Determine merge target
- Get the current branch:
git rev-parse --abbrev-ref HEAD - Determine the main branch name:
git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@'— fallback tomainif not set. - If current branch == main branch → already on main, skip merge (commit alone is the result). Go to Step 9.
- Otherwise, the current branch is a feature branch. Proceed to merge.
Substep 8d — Locate the main worktree
git worktree list --porcelain lists all worktrees. Find the one whose branch is refs/heads/<main-branch>. That's the main worktree path.
If no worktree is checked out on main (e.g., main was detached or main branch has no worktree), stop and tell the user: they need to check out main somewhere before auto-merge can run.
Substep 8e — Merge feature branch into main
# From the main worktree directory
cd <main-worktree-path>
git merge --no-ff -m "Merge branch '<feature-branch>'" <feature-branch>Handle outcomes:
- Clean merge: report success with the new main HEAD hash. Done.
- Conflict: stop immediately. Report which files conflict. Do NOT try to auto-resolve — tell the user to resolve and commit manually, or to abort with
git merge --abort. - Other failure: report the exact error; do not retry.
Substep 8f — Safety constraints (must not violate)
- NEVER run
git push(push is a separate, explicit user action) - NEVER use
--force,--force-with-lease, or--no-verify - NEVER delete the worktree or the feature branch (per project memory: worktree deletion crashes running servers)
- NEVER touch the remote in any way
After a successful merge, tell the user:
Merged
<feature-branch>into<main-branch>(commit<hash>). Worktree and feature branch left in place — delete manually when ready (stop any server running from the worktree first).
Remove the session-scoped temporary files:
rm -f /tmp/claude-review-${REVIEW_ID}.md /tmp/codex-review-${REVIEW_ID}.mdRound 1: Claude sends [plan|diff] → Codex reviews → REVISE?
Round 2: Claude revises [plan|code] → Codex re-reviews (resume session) → REVISE?
Round 3: Claude revises → Codex re-reviews (resume session) → APPROVED
↓ (code mode only)
Auto-commit in current worktree → Auto-merge feature branch into main (local, no push)
Max 5 rounds. Each round preserves Codex's conversation context via session resume.
- Claude actively revises based on Codex feedback between rounds — this is NOT just passing messages, Claude should make real improvements
- In code review mode, Claude fixes BLOCKING issues only. NON_BLOCKING items are reported but not auto-fixed
- In code review mode, if a fix contradicts the user's explicit requirements or the project's CLAUDE.md rules, skip that fix and note it for the user
- Default model is
gpt-5.3-codex. Accept model override from the user's arguments (e.g.,/codex-review o4-mini) - Always use read-only sandbox mode — Codex should never write files
- Max 5 review rounds to prevent infinite loops
- Show the user each round's feedback and revisions so they can follow along
- If Codex CLI is not installed or fails, inform the user and suggest
npm install -g @openai/codex
- Runs only on VERDICT: APPROVED in code-review mode. Never for plan review. Never on max-rounds-reached-without-approval.
- Skip if the user has said "review only", "don't commit", or "don't merge" in the current invocation.
- Stage only files that appeared in the reviewed diff — never
git add -A/.(avoids staging secrets or unrelated untracked files). - Commit message: Claude writes a 1–2 line imperative subject from the diff it reviewed. Always include
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>. - On pre-commit hook failure: stop and report. Do NOT
--no-verify. Do NOT amend. - Merge target: the branch pointed to by
origin/HEAD(defaultmain), merged with--no-ff. If already on main, skip the merge step. - On merge conflict: stop immediately. Do not attempt to auto-resolve. Tell the user which files conflicted and let them resolve manually.
- NEVER
git push,--force,--force-with-lease, or--no-verify. - NEVER delete the worktree or feature branch (worktree deletion can crash a server running from its cwd).
- After a successful merge, explicitly remind the user to stop any server running from the worktree before they delete it.