codex-review

Codex Code Review

Review code changes using OpenAI's Codex CLI (codex review), then address any issues Codex raises, commit fixes, and re-review until Codex is satisfied.

Why this exists

Getting a second pair of AI eyes on code catches things the author (Claude) missed. The loop ensures issues are actually resolved rather than just acknowledged.

The review loop

Step 1: Run the initial review

codex review --commit HEAD 2>/dev/null

• 2>/dev/null suppresses thinking tokens on stderr — only show review output.
• If the user specifies a different commit, use that SHA instead of HEAD.
• The review runs in read-only mode by default (no sandbox flags needed).

Step 2: Parse and assess the review

Read Codex's output and categorize each issue:

• Actionable: Real bugs, logic errors, security issues, missing edge cases — things worth fixing.
• Stylistic/opinion: Naming preferences, comment suggestions, minor restructuring — skip these unless the user has asked for thoroughness.
• False positives: Misunderstandings of the codebase, outdated advice, or things that don't apply — note these but don't act on them.

Present a summary to the user:

• How many issues Codex found
• Which ones you plan to address (and why)
• Which ones you're skipping (and why)

Wait for the user to confirm before making changes. They may want to override your assessment.

Step 3: Fix and commit

Address the actionable issues. Commit the fixes as a new commit (not an amend) with a message like:

Address Codex review feedback

- Fix [brief description of fix 1]
- Fix [brief description of fix 2]

Step 4: Re-review

Run codex review --commit HEAD 2>/dev/null again on the new fix commit to verify the issues are resolved.

• If Codex finds new issues in the fix commit, repeat from Step 2.
• If Codex is clean (no actionable issues), report success to the user.
• Cap at 3 iterations to avoid infinite loops. If issues persist after 3 rounds, present the remaining issues to the user and ask how to proceed.

Disagreeing with Codex

Codex is a peer, not an authority. If Codex suggests something you know is wrong:

1. State your disagreement clearly to the user with evidence.
2. Optionally follow up via exec to discuss:

   echo "This is Claude following up. I disagree with [X] because [evidence]. What's your take?" | codex exec --skip-git-repo-check resume --last 2>/dev/null
   

3. Let the user make the final call.

Command reference

Action	Command
Review HEAD commit	codex review --commit HEAD 2>/dev/null
Review specific commit	codex review --commit <SHA> 2>/dev/null
Review uncommitted changes	codex review --uncommitted 2>/dev/null
Review against base branch	codex review --base main 2>/dev/null
Custom review instructions	codex review --commit HEAD "Focus on security" 2>/dev/null

Edge cases

• No recent commit: If the user asks for a review but hasn't committed yet, suggest codex review --uncommitted instead.
• Large commits: For commits touching many files, Codex may hit token limits. If the review seems truncated or shallow, mention this to the user and suggest reviewing file-by-file.
• Timeout: codex review can take 30-90 seconds. Use a 120s timeout on the bash call. If it times out, retry once before reporting failure.