codex-review

---
name: codex-review
description: Run OpenAI Codex CLI to review code changes and iterate until clean. Use this skill whenever the user says "codex review", "have codex check", "run codex on that", "codex loop", "review with codex", or asks you to get a second opinion on your commit from Codex/OpenAI. Also use when the user mentions wanting an automated review loop, cross-model review, or peer review from another AI on committed code.
---

# 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

```bash
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:
   ```bash
   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.