Codex Review

Codex Review - Second-Opinion Code & Decision Review

Runs OpenAI's Codex CLI (codex exec) headlessly to get independent analysis from a competing AI model. Use this when you want a second pair of eyes - a fundamentally different model reviewing your work, catching blind spots, or stress-testing decisions.

When to Use

• Code review: Get Codex to review a diff, PR, file, or set of changes
• Decision review: Stress-test an architectural or business decision
• Plan review: Have Codex critique an implementation plan before building
• Build review: Post-build audit of what was just implemented
• Codebase review: General codebase health check or specific area deep-dive

Prerequisites

Install Codex CLI

npm install -g @openai/codex

Authentication

Codex uses OAuth (cached at ~/.codex/auth.json). No API key needed if you have a ChatGPT Pro/Plus account.

If auth expires, re-authenticate:

codex login

Modes

1. Code Review (code)

Review specific files, diffs, or branches against main.

# Review uncommitted changes
codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" \
  "Review the uncommitted changes (run git diff). Focus on:
   - Correctness and edge cases
   - Security vulnerabilities
   - Performance issues
   - Code style and maintainability
   Report issues with file:line references. Be direct - no fluff."

# Review a specific file
codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" \
  "Review the file $FILE_PATH. Focus on correctness, security, performance, and maintainability. Report issues with line references."

# Review branch diff against main
codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" \
  "Review changes on this branch vs main (run git diff main...HEAD). Focus on correctness, security, and whether the implementation matches the intent. Be critical."

2. Decision Review (decision)

Stress-test an architectural, technical, or business decision.

codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" \
  "I'm considering the following decision:

$DECISION_DESCRIPTION

Context:
$CONTEXT

Play devil's advocate. What are the risks? What could go wrong? What alternatives should I consider? What am I not thinking about? Be blunt and direct."

3. Plan Review (plan)

Critique an implementation plan before building.

# Review a plan file
codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" \
  "Read the plan at $PLAN_FILE_PATH and critique it. Consider:
   - Is the approach sound? Are there better alternatives?
   - What's missing or underspecified?
   - What are the riskiest parts?
   - Is the sequencing right? Any dependency issues?
   - Is it over-engineered or under-engineered?
   Be specific and constructive."

4. Build Review (build)

Post-implementation audit of what was just built.

codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" \
  "Audit the recent changes on this branch (run git log --oneline -20 and git diff main...HEAD).
   Review what was built and assess:
   - Does the implementation look correct and complete?
   - Any bugs, edge cases, or security issues?
   - Is the code well-structured and maintainable?
   - Anything that should be refactored before merging?
   - Are there missing tests or error handling?
   Be thorough but prioritize actionable findings."

5. Codebase Review (codebase)

General health check or deep-dive into a specific area.

# General health check
codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" \
  "Explore this codebase. Understand the architecture, then provide:
   - Overall assessment of code quality and organization
   - Top 5 areas of concern (bugs, security, tech debt)
   - Specific recommendations with file:line references
   Focus on actionable findings, not style nitpicks."

# Targeted area review
codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" \
  "Deep-dive into the $AREA_DESCRIPTION area of this codebase.
   Review all relevant files and assess:
   - Correctness and edge cases
   - Security posture
   - Performance characteristics
   - Test coverage gaps
   Be specific with file:line references."

Workflow

1. Determine Mode and Target

Parse the user's request to identify:

• Mode: code, decision, plan, build, or codebase
• Target: file path, branch name, plan file, or inline description
• Project directory: Which project to review

If unclear, ask the user. Default to code mode reviewing uncommitted changes.

2. Set Up Environment

# Verify codex is installed and authenticated
which codex || npm install -g @openai/codex

Auth is handled via cached OAuth session (~/.codex/auth.json). If auth fails, run codex login.

3. Build and Execute the Prompt

Construct the appropriate prompt based on mode (see templates above). Always include:

• Clear scope (what to review)
• Specific focus areas
• Instruction to be direct and cite file:line references
• The project directory via -C

Run with --full-auto for headless operation. Capture output:

CODEX_OUTPUT=$(codex exec --full-auto -m gpt-5.4 -C "$PROJECT_DIR" "$PROMPT" 2>/dev/null)

4. Synthesize and Present

After receiving Codex's output:

1. Present Codex's findings clearly, attributed as "Codex found:"
2. Add your own assessment - agree, disagree, or add nuance to each finding
3. Highlight disagreements - where Claude and Codex see things differently, this is the most valuable signal
4. Prioritize - rank findings by severity/impact
5. Recommend actions - concrete next steps based on the combined review

Format the output as:

## Codex Review Results

### Findings

| # | Severity | Finding | Location | Claude's Take |
|---|---|---|---|---|
| 1 | High | ... | file:line | Agree / Disagree / Nuance |

### Key Disagreements
[Where Claude and Codex see things differently]

### Recommended Actions
1. ...
2. ...

5. Interactive Follow-up

After presenting results, offer:

• "Want me to fix any of these issues?"
• "Want me to ask Codex to dig deeper into any specific finding?"
• "Want me to run another review with a different focus?"

Multi-Turn Review Sessions

For complex reviews, run multiple Codex passes:

# Pass 1: High-level review
PASS1=$(codex exec --full-auto -m gpt-5.4 -C "$DIR" "Review the codebase architecture and flag top concerns" 2>/dev/null)

# Pass 2: Deep-dive on concerns from Pass 1
PASS2=$(codex exec --full-auto -m gpt-5.4 -C "$DIR" "Focus on these specific areas: $CONCERNS_FROM_PASS1. Provide detailed analysis with code examples." 2>/dev/null)

# Pass 3: Security-specific
PASS3=$(codex exec --full-auto -m gpt-5.4 -C "$DIR" "Security audit: check for injection, auth bypass, data exposure, SSRF, and other OWASP top 10 issues." 2>/dev/null)

Configuration

Model Selection

Always specify -m gpt-5.4 (flagship). The CLI defaults to a lesser model if not specified.

Available models (as of March 2026):

• gpt-5.4 - Flagship frontier model (always use this)
• gpt-5.3-codex - Optimised for pure code tasks (CLI default)
• gpt-5.3-codex-spark - Fastest, good for quick checks

Sandbox

--full-auto uses workspace-write sandbox with auto-approval. Since we're only reading (reviewing), this is safe. For pure read-only:

codex exec -s read-only -C "$DIR" "$PROMPT"

Edge Cases

• Codex not installed: Install with npm install -g @openai/codex and retry
• Auth expired: Run codex login to re-authenticate via browser OAuth
• Large codebase: Scope to specific files/directories rather than whole-repo review
• Codex disagrees with Claude: Present both perspectives - the disagreement itself is valuable signal
• Codex hallucinates file paths: Cross-check all file:line references before presenting to user
• Empty diff: If reviewing uncommitted changes and there are none, tell the user and offer alternatives

Example Invocations

/codex-review code                         # Review uncommitted changes
/codex-review code src/api/handler.py      # Review a specific file
/codex-review decision "Migrate to Postgres?"  # Stress-test a decision
/codex-review plan docs/migration-plan.md  # Critique a plan
/codex-review build                        # Post-build audit
/codex-review codebase                     # General health check

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Peter-Moriarty
• Source: Peter-Moriarty/claude-code-multi-machine-setup
• License: MIT

Install and usage instructions live in the source repository linked above.