/codex-review

name: codex-review
description: OpenAI Codex CLI code review with GPT-5.2-Codex, CI/CD integration
when-to-use: When user requests Codex-powered code review or multi-engine review
user-invocable: true
effort: medium

OpenAI Codex Code Review Skill

Use OpenAI's Codex CLI for specialized code review with GPT-5.2-Codex - trained specifically for detecting bugs, security flaws, and code quality issues.

**Sources:** [Codex CLI](https://developers.openai.com/codex/cli/) | [GitHub](https://github.com/openai/codex) | [Code Review Cookbook](https://cookbook.openai.com/examples/codex/build_code_review_with_codex_sdk)

---

Why Codex for Code Review?

| Feature | Benefit | |---------|---------| | **GPT-5.2-Codex** | Specialized training for code review | | **88% detection rate** | Bugs, security flaws, style issues (LiveCodeBench) | | **Structured output** | JSON schema for consistent findings | | **GitHub native** | `@codex review` in PR comments | | **Headless mode** | CI/CD automation without TUI |

---

Installation

Prerequisites

# Check Node.js version (requires 22+)
node --version

# Install Node.js 22 if needed
# macOS
brew install node@22

# Or via nvm
nvm install 22
nvm use 22

Install Codex CLI

# Via npm (recommended)
npm install -g @openai/codex

# Via Homebrew (macOS)
brew install --cask codex

# Verify installation
codex --version

Authentication

**Option 1: ChatGPT Subscription** (Plus, Pro, Team, Edu, Enterprise)

codex
# Follow prompts to sign in with ChatGPT account

**Option 2: OpenAI API Key**

# Set environment variable
export OPENAI_API_KEY=sk-proj-...

# Or add to shell profile
echo 'export OPENAI_API_KEY=sk-proj-...' >> ~/.zshrc

# Run Codex
codex

Shell Completions (Optional)

# Bash
codex completion bash >> ~/.bashrc

# Zsh
codex completion zsh >> ~/.zshrc

# Fish
codex completion fish > ~/.config/fish/completions/codex.fish

---

Interactive Code Review

Launch Review Mode

# Start Codex
codex

# In the TUI, type:
/review

Review Presets

| Preset | Use Case | |--------|----------| | **Review against base branch** | Before opening PR - diffs against upstream | | **Review uncommitted changes** | Before committing - staged + unstaged + untracked | | **Review a commit** | Analyze specific SHA from history | | **Custom instructions** | e.g., "Focus on security vulnerabilities" |

Example Session

$ codex
> /review

Select review type:
❯ Review against a base branch
  Review uncommitted changes
  Review a commit
  Custom review instructions

Select base branch: main

Reviewing changes...

┌─────────────────────────────────────────────────────────────┐
│ CODE REVIEW FINDINGS                                        │
├─────────────────────────────────────────────────────────────┤
│ 🔴 CRITICAL: SQL Injection vulnerability                    │
│    File: src/api/users.ts:45                                │
│    Issue: User input directly interpolated in query         │
│    Fix: Use parameterized queries                           │
├─────────────────────────────────────────────────────────────┤
│ 🟠 HIGH: Missing authentication check                       │
│    File: src/api/admin.ts:23                                │
│    Issue: Admin endpoint accessible without auth            │
│    Fix: Add requireAuth middleware                          │
├─────────────────────────────────────────────────────────────┤
│ 🟡 MEDIUM: Inefficient database query                       │
│    File: src/services/orders.ts:89                          │
│    Issue: N+1 query pattern in loop                         │
│    Fix: Use batch query or JOIN                             │
└─────────────────────────────────────────────────────────────┘

---

Headless Mode (Automation)

Basic Usage

# Simple review
codex exec "review the code for bugs and security issues"

# Review with JSON output
codex exec --json "review uncommitted changes" > review.json

# Save final message to file
codex exec --output-last-message review.txt "review the diff against main"

Full Automation (CI/CD)

# Full auto mode (use only in isolated runners!)
codex exec \
  --full-auto \
  --json \
  --output-last-message findings.txt \
  --sandbox read-only \
  -m gpt-5.2-codex \
  "Review this code for bugs, security issues, and performance problems"

Structured Output with Schema

# Define output schema
cat > review-schema.json << 'EOF'
{
  "type": "object",
  "properties": {
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "severity": { "enum": ["critical", "high", "medium", "low"] },
          "title": { "type": "string" },
          "file": { "type": "string" },
          "line": { "type": "integer" },
          "description": { "type": "string" },
          "suggestion": { "type": "string" }
        },
        "required": ["severity", "title", "file", "description"]
      }
    },
    "summary": { "type": "string" },
    "approved": { "type": "boolean" }
  },
  "required": ["findings", "summary", "approved"]
}
EOF

# Run with schema validation
codex exec \
  --output-schema review-schema.json \
  --output-last-message review.json \
  "Review the staged changes and output findings"

---

GitHub Integration

Option 1: PR Comment Trigger

In any pull request, add a comment:

@codex review

Codex will respond with a standard GitHub code review.

Option 2: GitHub Action

# .github/workflows/codex-review.yml
name: Codex Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Codex Review
        uses: openai/codex-action@main
        with: