Codex Review

Run a local Codex CLI review of changes in this repo with a prompt that encodes the multi-tenant, auth, and migration invariants Codex won't infer on its own. Output is a severity-grouped report (CRITICAL → LOW) with file:line — problem — fix lines.

When to Use

• User asks for a Codex review (any phrasing)
• About to commit/PR and wants a second pair of eyes that isn't Claude
• Reviewing a risky slice (auth, migrations, admin routes) and wants independent verification

Do NOT use for: PR-level review on GitHub (that's the Codex GitHub app, not the CLI), or when the user wants Claude to do the review itself.

Workflow

1. Preflight   → Codex installed? Authenticated? Diff non-empty?
2. Scope       → choose git diff (branch / staged / file / area)
3. Tailor      → append "Focus areas" block when high-risk files touched
4. Run         → cat diff | codex exec ... > /tmp/codex-review.out
5. Triage      → surface CRITICAL + HIGH to user; verify each before acting

Skip any step only if it's a no-op for the scope (e.g. no high-risk files → no Focus areas).

1. Preflight (gate the run)

codex --version          # else: npm install -g @openai/codex && codex login
tessl whoami 2>/dev/null # unrelated; for codex use: codex login

If codex --version fails, install + login first. Login is interactive — must run in a real terminal, not via Claude !-shell.

2. Build the diff

Always write to /tmp/codex-review.diff first (avoids shell-quoting issues with large diffs). Pick scope:

git diff main...HEAD > /tmp/codex-review.diff
test -s /tmp/codex-review.diff || { echo "empty diff — nothing to review"; exit 0; }

The test -s guard is mandatory: an empty diff makes Codex hallucinate findings about whatever it reads from the repo.

For 30+ file diffs, split before running — output quality degrades. Two parallel passes on backend/frontend beat one big pass.

3. Tailor with Focus Areas

Skim git diff --stat. If any of these patterns are touched, append a Focus areas block to the prompt at the CLI:

• backend/src/routes/auth.ts, backend/src/middleware/auth.ts
• backend/src/routes/admin/**
• backend/src/db/migrations/** + backend/src/db/templates/company_schema_template.sql
• backend/src/server.ts (middleware order)
• backend/src/services/scheduler/schedulerRegistrations.ts (cron strings)
• Any BedrockClient consumer (prompt-injection surface)

4. Run Codex

Single canonical invocation:

cat /tmp/codex-review.diff \
  | codex exec --sandbox read-only "$(cat .claude/skills/codex-review/resources/PROMPT.md)
$FOCUS_AREAS" \
  > /tmp/codex-review.out

Where $FOCUS_AREAS is an optional inline block:

## Focus areas in THIS diff
- backend/src/routes/auth.ts — scrutinize token handling and error leakage
- backend/src/db/templates/company_schema_template.sql — confirm matches any new migration tables

Notes:

• codex exec has no --file flag — diff goes via stdin.
• --sandbox read-only lets Codex grep the repo for cross-references without write risk.
• Uses your configured Codex model (typically gpt-5.5 at xhigh reasoning per ~/.codex/config.toml).

Single file, interactive (skip the workflow)

codex
> review backend/src/routes/auth.ts for auth bypass, timing attacks, and error leakage.
  Use the invariants in .claude/skills/codex-review/resources/PROMPT.md.

Run from Claude Code (output visible in chat)

Tell the user to type:

! cat /tmp/codex-review.diff | codex exec "$(cat .claude/skills/codex-review/resources/PROMPT.md)"

5. Triage Findings

After the run completes:

1. Read /tmp/codex-review.out. Surface every CRITICAL and HIGH to the user — one line each, in plain prose.
2. For each CRITICAL/HIGH the user asks to fix: verify against the actual code before editing. Codex hallucinates line numbers, invents missing imports, and sometimes flags as bugs the deliberate design choices that have tests pinning the current behavior. The test suite is the source of truth, not Codex.
3. MEDIUM and LOW findings: summarize counts, surface details only if the user asks.

Common Mistakes