Codex Review

Independent Codex Review (CLI channel, read-only)

All reviews go through the local codex CLI, not MCP. Three modes, pick by need.

General Rules

• stdin must be handled explicitly, or codex hangs waiting for input and never starts: pass the prompt via stdin with - < /tmp/prompt.md; when the prompt goes via argv, you must append < /dev/null.
• -C only goes between exec and the subcommand: codex exec -C <repo> review ... is valid; codex exec review -C <repo> errors out.
• Long prompts: write to a temp file and pass via stdin (- < file), not argv.
• Write output to disk with -o <file> and read it back — don't parse the stdout stream; timestamp the filename so parallel runs don't overwrite each other (e.g. /tmp/codex_review_$(date +%s).md); $OUT in the templates below refers to it.
• Reviews are strictly read-only: add --sandbox read-only to codex exec; codex exec review is itself a read-only reviewer. Never --dangerously-bypass-approvals-and-sandbox.
• Pin the reasoning effort: always add -p high for reviews (~/.codex/high.config.toml, containing only model_reasoning_effort = "high"). The main config gets dynamically rewritten by the Codex app, so the effort there is not under your control — don't rely on it. Pass -m / higher effort only when the user names it.
• One review per run; split unrelated review requests into separate runs.

Size Estimate (do this before every review)

git -C "<repo>" status --short --untracked-files=all
git -C "<repo>" diff --shortstat; git -C "<repo>" diff --shortstat --cached
# for branch review: git -C "<repo>" diff --shortstat main...HEAD

• Untracked files count as reviewable work; only reply "nothing to review" when the working tree AND the target diff are both empty.
• 1–2 small files: wait in the foreground (Shell block_until_ms: 300000, usually 1–3 minutes).
• Larger or unsure: run in the background (block_until_ms: 0), keep working on other things, wait for the completion notification.

Mode A: Native code review (first choice whenever there's a git diff)

Codex's built-in reviewer collects the diff automatically and ships its own dedicated review prompt — better than hand-feeding a diff. Must be inside a git repo.

codex exec -C "<repo>" -p high review -o "$OUT" --uncommitted   # uncommitted changes (incl. untracked)
codex exec -C "<repo>" -p high review -o "$OUT" --base main     # current branch vs a baseline
codex exec -C "<repo>" -p high review -o "$OUT" --commit <sha>  # a single commit

Mode B: Adversarial review (attack the design and direction, not just code details)

Native reviewer + custom adversarial instructions (passed via stdin):

codex exec -C "<repo>" -p high review -o "$OUT" --base main - <<'EOF'
You are doing an adversarial review: your job is to break this change, not to approve it.
- Default to suspicion: assume it fails in hidden, expensive ways until the evidence says otherwise.
- Attack first: permission/trust boundaries, data loss or corruption, rollback and partial failure, races and reentrancy, null/timeout/degradation paths, migration and compatibility.
- Question the direction itself: would a simpler or safer implementation be better? Which assumptions collapse under pressure?
- For every finding answer four things: where it breaks (file + line), why that path is fragile, how big the impact is, and concretely how to fix it; include a confidence level.
- Only report significant issues you can defend from the code; label "directly observed" vs "inferred" separately.
- One strong finding beats several weak ones; don't report style nits; if you genuinely think it's safe, say so plainly — don't pad.
Review focus: <user-specified focus; delete this line if none>
EOF

Mode C: General second opinion (no diff: verify a conclusion, review a design, judge a root cause)

codex exec --sandbox read-only --skip-git-repo-check -C "<working-dir>" -p high \
  -o "$OUT" - < /tmp/codex_prompt.md

Write the prompt as a block-structured contract (add -c tools.web_search=true if online verification is needed):

<task>Independently verify the following conclusion — do not just agree with me. Conclusion: ... Evidence: ... Relevant files: ...</task>
<grounding_rules>Verify each point yourself; label every judgment as confirmed / refuted / unverifiable + why; cite specific files and line numbers; separate observation from inference.</grounding_rules>
<compact_output_contract>Output order: verdict (agree / disagree / partially agree) → disagreements ranked by importance → risks I missed → residual uncertainty. Be concise; don't restate the background.</compact_output_contract>

Result-Handling Discipline (when presenting Codex output)

• Findings sorted by severity go first; quote file paths and line numbers verbatim, don't rewrite them.
• Preserve evidence boundaries: whatever Codex marked as inferred, uncertain, or to-be-verified stays marked that way — never flatten it into a firm conclusion.
• No findings? Say "no significant issues found" plainly, add one line of residual risk, and don't pad.
• After presenting review results, STOP: never auto-apply fixes (even obvious ones) — ask the user which findings to fix first.
• If the Codex run fails: report the most useful stderr lines and stop; never pass off your own analysis as Codex's second opinion — independent verification of a high-risk conclusion must actually happen; retry through another channel rather than skipping it.

Follow-ups and Re-review

The terminal log file header at launch contains session id: <uuid> — note it down; resume with the id, not --last (with parallel codex runs, --last resumes the wrong session):

codex exec resume <session-id> -o "$OUT" "Follow-up: only answer whether X holds, with evidence" < /dev/null

Send only incremental instructions, don't restate everything; open a new session only when the review direction changes substantially. Only fall back to resume --last if you didn't record the id AND you've confirmed no other codex run happened in the meantime.

Background Job Management

Progress: watch the corresponding terminal file (stdout streams to disk). Cancel: kill <pid> using the pid in the terminal file header. Completion triggers an automatic notification.

Ballpark Timings

A smoke-test short Q&A takes ~7 seconds; an architecture review with online verification takes 1–4 minutes in practice; a large diff review can take up to 10 minutes.