Codex Review

Use OpenAI Codex CLI to get an independent AI review of code changes.

When to Use

• User explicitly asks for a codex review, second opinion, or cross-review
• User says "run codex", "codex review", "/codex-review"
• User wants an independent AI to verify Claude's work before merging

Prerequisites

• codex CLI must be installed (which codex)
• An OpenAI API key must be configured for codex

Workflow

Step 1: Determine the Review Scope

Identify what to review:

# Option A: Review current branch against main
git log --oneline main..HEAD | head -20

# Option B: Review uncommitted changes
git diff --stat

# Option C: Review a specific commit
git show --stat <sha>

Pick the right codex review flag:

• Branch review: --base main (or whatever the base branch is)
• Uncommitted changes: --uncommitted
• Single commit: --commit <sha>

Step 2: Analyze the Changes and Build Instructions

Read the diff to understand what areas need review focus. Build a focused instruction file based on the actual code changes.

# Get the diff summary
git diff --stat <base>..HEAD

# Identify key areas
git diff --name-only <base>..HEAD | sed 's|/[^/]*$||' | sort -u

Write a focused instruction file to /tmp/codex-review-instructions.md:

You are reviewing [brief description of what changed].

Focus your review on:
1. [Area 1 based on actual changes]
2. [Area 2 based on actual changes]
3. [Area 3 based on actual changes]

Verify each finding against the actual code. Read the relevant
source files before reporting.

Key principles for instructions:

• Be specific about what changed — generic instructions get generic results
• List previously known issues so codex doesn't re-report them
• Focus on the areas where bugs are most likely (security, concurrency, edge cases)
• Tell codex to verify findings against actual code before reporting

Step 3: Run Codex Review

codex review \
  --base <base-branch> \
  --title "<descriptive title>" \
  -c 'sandbox_permissions=["disk-full-read-access","disk-full-write-access","network-full-access"]' \
  -c 'instructions="/tmp/codex-review-instructions.md"' \
  2>&1

Important flags:

• sandbox_permissions — codex needs read access to verify findings against source
• instructions — points to the focused review file from Step 2
• Always capture stderr with 2>&1 (codex logs to stderr)

Run this in the background if the review is expected to take long:

• Use run_in_background on the Bash tool
• The output will be available when the command completes

Step 4: Parse and Report Findings

Read the codex output and extract findings. Look for lines matching:

• [P1], [P2], [P3] — prioritized findings
• Full review comments: — start of findings section
• File paths with line numbers — specific locations

Report findings to the user in a clear table:

| # | Priority | Description | File:Line |
|---|----------|-------------|-----------|
| 1 | P1       | ...         | ...       |

Step 5: Fix Findings (if requested)

If the user wants to fix the findings:

1. Read each cited file to verify the finding is real
2. Apply fixes
3. Run tests and typecheck
4. Commit the fixes

Step 6: Iterate (if requested)

For thorough review, run multiple rounds:

1. Fix findings from round N
2. Update instructions to list all previously fixed issues
3. Run round N+1 with the updated instructions
4. Repeat until findings converge to zero

Critical for iteration: Always add previously fixed issues to the instruction file's exclusion list. Otherwise codex will re-report the same issues every round, wasting time and API costs.

Example: Branch Review

# 1. Write instructions
cat > /tmp/codex-review-instructions.md << 'EOF'
You are reviewing a new authentication module.

Focus on:
1. SECURITY: JWT validation, token expiry, session management
2. CORRECTNESS: Error handling, edge cases, missing null checks
3. TESTING: Are there tests for error paths?

Verify each finding against the actual code before reporting.
EOF

# 2. Run review
codex review \
  --base main \
  --title "feat(auth): security review" \
  -c 'sandbox_permissions=["disk-full-read-access"]' \
  -c 'instructions="/tmp/codex-review-instructions.md"' \
  2>&1

Example: Iterative Deep Review

# Round 2 instructions (after fixing round 1 findings)
cat > /tmp/codex-review-instructions.md << 'EOF'
Round 2 review. Prior fixes (do NOT re-report):
- SQL injection in user query (parameterized)
- Missing auth check on /api/admin (added middleware)
- XSS in profile page (escaped output)

Focus on genuinely NEW issues only.
EOF

codex review --base main \
  --title "feat(auth): review round 2" \
  -c 'sandbox_permissions=["disk-full-read-access"]' \
  -c 'instructions="/tmp/codex-review-instructions.md"' \
  2>&1

Safety Rules

Failure Modes

• Codex not installed: Check which codex first, tell user to install
• No API key: Codex will fail with auth error — user needs to configure
• Too large diff: Codex may truncate; break into smaller review scopes
• Repeated findings: Always maintain the exclusion list between rounds
• False positives: Always read the cited code before acting on findings