Codex Codebase Review

Purpose

Review large codebases (50-500+ files) that exceed single-session context limits. Splits codebase into module-based chunks, reviews each in an independent Codex session, then Claude synthesizes cross-cutting findings across modules.

Prerequisites

Source files in working directory.
codex CLI is installed and authenticated.
codex-review skill pack is installed (npx github:lploc94/codex_skill).

Runner

RUNNER="{{RUNNER_PATH}}"

Workflow

Collect inputs: effort level, parallel factor, focus areas.
Discovery: detect project type, list source files, identify module boundaries.
Chunking: group files into 500-2000 line chunks, present chunk plan.
Review loop: for each chunk — build prompt, node "$RUNNER" start, poll, parse ISSUE-{N}, propagate context.
Cross-cutting analysis: Claude synthesizes all chunk findings — inconsistencies, API contracts, DRY violations, integration, architecture.
Validation (effort >= high): feed CROSS-{N} findings to Codex for verification.
Final report: overview table, per-module findings, cross-cutting findings, action items.
Cleanup: stop ALL tracked STATE_DIRs — always runs regardless of outcome.

Effort Level Guide

| Level | Discovery | Cross-cutting | Validation | |----------|------------------|------------------|--------------| | low | Auto-detect only | Basic (2 cats) | Skip | | medium | Auto + confirm | Standard (3 cats)| Skip | | high | Full + confirm | Full (5 cats) | 1 round | | xhigh | Full + suggest | Full + arch | 2 rounds |

Required References

Detailed orchestration: references/workflow.md
Prompt templates: references/prompts.md
Output contract: references/output-format.md

Rules

Codex reviews only; it does not edit files.
No cross-contamination between chunk sessions — each chunk is independent.
Context propagation: only high/critical findings from prior chunks, capped at ~2000 tokens.
Cleanup always runs — stop every tracked STATE_DIR regardless of outcome.
Scope is full codebase only — for diff review use /codex-impl-review.