Codex Review

Prerequisites

• Codex CLI installed and authenticated: npm install -g @openai/codex then codex login
• An OpenAI account with access to GPT-5.4 and GPT-5.2 (or adjust model names below)

Roles

• Codex (Model A + Model B): Two independent reviewers examining the same code simultaneously, unaware of each other
• Claude: Controller + arbitrator. Constructs prompts, dispatches both models in parallel, compares findings, adjudicates disagreements, makes final decisions

Modes

autopilot mode: When the user is away and Claude is executing code tasks autonomously. After Codex review results come back, Claude arbitrates and decides whether to fix without asking the user. Decision criteria:

1. PRD documentation is the ultimate judge — if the PRD explicitly states something, follow the PRD
2. If the PRD doesn't cover it, check existing code behavior before deciding
3. Only record items needing confirmation when they involve product direction / business logic tradeoffs; batch-report at the end

Autopilot is not the default — requires explicit user request ("autopilot", "unattended", "run without me").

Post-Arbitration Action Classification

After arbitration, Claude handles each finding by these rules:

Fix directly (don't ask the user):

• Code bugs, compile/runtime errors
• Documentation wording / phrasing contradictions (not direction choices)
• Inconsistencies with explicit PRD decisions
• Security vulnerabilities

Must ask the user (don't skip any):

• Product/business decisions needed (feature tradeoffs, scope changes)
• User-provided information needed (credentials, domains, third-party service configs)
• Choices affecting user experience not covered by PRD
• Cost/budget decisions

In autopilot mode, "must ask" items are accumulated and batch-reported at the end without interrupting execution.

Dual-Model Parallel Review

Each review dispatches two parallel codex exec calls via Bash, one per model:

# Model A (run in parallel with Model B)
codex exec -m "gpt-5.4" -s "read-only" -C "$REPO_DIR" \
  --skip-git-repo-check --ephemeral \
  -o /tmp/codex-review-a.md \
  - <<'PROMPT'
[constructed prompt here]
PROMPT

# Model B (run in parallel with Model A)
codex exec -m "gpt-5.2" -s "read-only" -C "$REPO_DIR" \
  --skip-git-repo-check --ephemeral \
  -o /tmp/codex-review-b.md \
  - <<'PROMPT'
[same prompt here]
PROMPT

Both calls use the same prompt but different models. Wait for both results before entering arbitration.

For fix mode, only one model executes the fix (default Model A), but the review phase still uses both models:

codex exec -m "gpt-5.4" -s "workspace-write" -C "$REPO_DIR" \
  --skip-git-repo-check --full-auto \
  -o /tmp/codex-fix.md \
  - <<'PROMPT'
[fix prompt here]
PROMPT

To resume a session (for review-fix-review cycles):

codex exec resume SESSION_ID "follow-up prompt here"

The session ID is printed in the codex exec output header (look for session id: xxx).

Arbitration: Claude as Judge

When both sets of findings arrive, Claude processes them in three zones:

Consensus zone — Both models flagged the same issue. Essentially confirmed; adopt directly. If fix suggestions differ, pick the one with harder evidence (file:line + code quote > vague description).

Single-source zone — Only one model flagged it. Claude reads the code to verify:

• Hard evidence (specific line + reproducible logic chain) → adopt
• Soft evidence ("might be a problem" without pinpointing) → downgrade to suggestion, don't force fix
• Claude judges it's a false positive → discard, explain reasoning in output

Conflict zone — Two models disagree (A says problem, B says fine). Claude reads the code and rules. If unresolvable (e.g., business logic judgment), escalate to user.

Output format: Tag each finding with its source — [A+B] consensus, [A] or [B] single-source, [Conflict→Claude] conflict. User sees at a glance which findings are iron-clad vs. single opinions.

Invocation Parameters

-C must be set to the current working directory (Codex needs access to the same codebase).

Don't embed file contents in the prompt — Codex can read files itself. Only provide absolute paths in the prompt and let Codex read them. Save the token budget for review requirements, context, and focus areas.

Use --ephemeral for one-shot reviews (no session persistence needed). Omit it when you plan to do review-fix-review cycles.

Use --skip-git-repo-check when the target directory isn't a git repo.

Maximize initial review input — On the first call, give Codex the full review scope up front. Locating code is the most expensive phase of the first review; specific paths and ranges skip it entirely:

• Required: Complete file path list (not vague like "the marketing-related files")
• Required: Line ranges of interest (path:line-range) or precise diff range (<base>..<head> commit range / direct patch)
• Required: Hard boundaries — which files/modules are context vs. review targets
• Required: Internal checks already run (lint / typecheck / key grep results), so Codex doesn't repeat them
• Principle: The more specific the file list in the first prompt, the shorter the review runs. Put the detail in the first prompt — don't wait for Codex to ask.

⚠️ Hard constraint — the path list is a locator, not a scope cap: The prompt must tell Codex explicitly — the file list/line ranges are locators to help you find entry points quickly, NOT a scope lock restricting your review to only these paths. Codex's review must be as comprehensive as possible:

• Follow call chains; inspect files outside the list if they are affected
• Check cross-file side effects, error paths, edge cases — don't constrain yourself to the listed paths
• If you find issues outside the list, report them. Do NOT skip findings with "not in the given scope" reasoning

Include language like this in the prompt:

"The file list above is a locator to save you from scanning the repo from scratch. It is NOT a scope lock. Your review must be comprehensive — follow call chains, inspect files outside the list if they are affected, and report any issues you find there. Do not limit findings to the listed paths."