codex-review

Cross-Model Code Review with Codex CLI

Cross-model validation using the codex binary directly. Claude writes code, Codex reviews it. Different architecture, different training distribution, no self-approval bias.

Core insight: Single-model self-review is systematically biased. Cross-model review catches different bug classes because the reviewer has fundamentally different blind spots than the author.

Scope the independence claim honestly: a different model breaks self-review bias — nothing else. It does not catch shared-training staleness (version, SOTA, and ecosystem claims need live primary sources no matter how many models agreed) or intent misreads inherited from the brief (carry the user's verbatim ask into the prompt and ask the reviewer to challenge the interpretation).

How to read this skill: the patterns and decision tables below are guidelines. Pick what fits, blend when needed. The rules marked ⚠️ are different: they're real codex CLI behaviors, not procedural ceremony. Skipping the scope flag genuinely hangs the call; piping to tail genuinely loses output. Treat ⚠️ rules as facts about the tool, not opinions about workflow.

Prerequisite: The codex CLI must be installed and authenticated. Verify with codex --version. User defaults live in ~/.codex/config.toml; respect them.

On Pi: when the pi-nova xreview extension is installed, prefer /xreview — it wraps external codex exec --sandbox read-only with stdin closed and returns structured Verdict/Findings/Fix Queue. Manual bash calls from Pi follow the same ⚠️ rules below.

Direction: Claude → Codex only. For the bidirectional skill (also handles Codex → Claude with the claude -p gotchas around yield_time_ms and variadic flags), use /hyperskills:cross-model-review instead.

---

⚠️ Non-Negotiable Rule: Always pass a scope flag to codex review

A bare codex review (no scope) is the #1 cause of failures: it hangs or produces 100KB+ blob output. Always specify exactly one scope flag:

Want to review	Command
Branch since main	codex review --base main
Single commit	codex review --commit <SHA>
Working tree (unstaged)	codex review --uncommitted

Scoped codex review also accepts custom instructions as a trailing [PROMPT] argument (as of Jul 2026: codex review --base main "focus on error handling"), so a focused pass keeps structured review behavior. Reach for codex exec "PROMPT" when the artifact isn't a diff at all — spec docs, single files outside version control, freeform investigations — never bare codex review.

If codex review output exceeds ~100KB, the diff is too large for one pass. Split per commit, or use codex exec with a narrower prompt ("Review error handling only"). Large codex exec transcripts are a different animal — see When the Review Hangs.

Pin the surface, freeze the target. On a dirty or multi-workstream branch, give an explicit file list or pipe the exact diff into codex exec — an unpinned reviewer wanders into diff tourism. Don't edit the reviewed code while the review runs; fill the wait with work that's read-only relative to the reviewed diff. Any edit after the verdict voids it: re-review exactly the delta, so the blocker is closed rather than hand-waved.

---

⚠️ Capture Output to a File: Don't Pipe to tail

Never pipe a review to | tail -N. Three failure modes:

1. The pipe buffers until EOF. tail reads the whole stream before producing output, so the agent gets nothing until codex exits or times out, no progress signal mid-review.
2. Reviews put the verdict near the top, not the bottom. Findings sort by severity (BLOCKER first), so tail -300 cuts exactly the part you want.
3. A file lets a human watch progress live. tail -f /tmp/review.txt in another terminal streams the review in real time, completely independent of the agent's call.

Right pattern: pick a non-colliding filename, redirect, then read it back.

# mktemp so parallel/repeat reviews don't clobber each other.
# Bake the scope into the slug so it's self-describing under tail -f.
out=$(mktemp -t codex-review-pre-pr.XXXXXX) && echo "$out"

codex review --base main > "$out" 2>&1
codex exec --sandbox read-only "PROMPT" > "$out" 2>&1

If mktemp isn't handy: out=/tmp/codex-review-$$-$(date +%s).txt. Echo the path before the redirect so a human running tail -f knows where to look. After exit, Read (or cat) the file. It persists across turns, re-read instead of re-running.

Adjacent tool fact: under --sandbox read-only, Codex silently can't write a report file the prompt asks for. Capture via redirect or --output-last-message, never "write your report to X".

---

When the Review Hangs

Even correctly-scoped reviews hang — it's the top operational failure in the field. The output file is the liveness instrument: judge by growth and process state, never elapsed time. Slow with growing output is often a quality signal — a fast rubber stamp on a big surface is suspicious.

Signal	Move
Output file growing	Keep waiting; it's working
Empty file, process tree alive	Wait one more window, then isolate variables (as of Jul 2026, wedged MCP servers and startup hooks are the usual culprits)
Empty file, process wedged	Kill only that process tree; retry once with fewer degrees of freedom — exact diff on stdin, narrower file list, lower effort. Same question, less payload
Retry also sticks	Pre-declare the give-up, record the failed review honestly

Never spawn a duplicate alongside a live reviewer — reap the one you have. And size alone is not the failure signal: a 1MB+ codex exec transcript can be a successful deep exploration with the verdict at the tail — grep for verdict and severity markers instead of dumping the trace. The real failure shape is no output growth, or growth with no convergence toward a verdict.

---

Two Ways to Invoke Codex

Mode	Command	Best For
codex review	Structured diff review with prioritized findings	Pre-PR reviews, commit reviews, WIP checks
codex exec	Freeform non-interactive deep-dive with full prompt control	Security audits, architecture, focused investigation, specs

Scope flags (codex review only)

Flag	Purpose
--base <BRANCH>	Diff against base branch
--commit <SHA>	Review a specific commit
--uncommitted	Review working tree changes

Sandbox & ergonomics flags (both modes)

Flag	When
--sandbox read-only	Default for review work, no writes
--sandbox workspace-write	Review + apply suggested fixes
--full-auto	Alias for --ask-for-approval never --sandbox workspace-write
--dangerously-bypass-approvals-and-sandbox	Last resort; explicit user request only
-C <DIR> / --cd <DIR>	Run in another worktree without cd
--skip-git-repo-check	Running from /tmp or any non-repo dir (trips the git trust check)
--add-dir <DIR>	Extend read access to another path
--ephemeral	One-shot session, no persistence
--json / --output-last-message <FILE>	Capture structured output to a file
-c model_reasoning_effort="xhigh"	Spec/RFC review only (see Effort Policy)

Effort override policy

Reviewing	Effort flag
Code (commit / diff / PR / WIP)	None, defer to ~/.codex/config.toml
Spec / RFC / design doc	-c model_reasoning_effort="xhigh"

Specs are higher-stakes than diffs, a subtle architectural mistake compounds across the eventual implementation. Code diffs are smaller scope and the user's configured effort is fine.

Scope before effort. Effort amplifies whatever the scope is; the xhigh override applies to an already-scoped spec review. An unscoped "verify everything" prompt at xhigh diverges instead of deepening (observed: 80k lines of transcript, no verdict). When a review must converge, narrow the scope — and consider lower effort, not higher — with an explicit convergence budget in the prompt ("be surgical, converge to a verdi

---

Content truncated.