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:
- The pipe buffers until EOF.
tailreads the whole stream before producing output, so the agent gets nothing until codex exits or times out, no progress signal mid-review. - Reviews put the verdict near the top, not the bottom. Findings sort by severity (BLOCKER first), so
tail -300cuts exactly the part you want. - A file lets a human watch progress live.
tail -f /tmp/review.txtin 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 verdict").
Never specify --model, -m, or -c model= to override the model itself. User config is authoritative. The gate's value is the full agentic Codex with repo access — not a one-shot API call.
Review Patterns
Pattern 1: Pre-PR Full Review (default)
The standard review before opening a PR. Use for any non-trivial change.
Step 1, structured review (catches correctness + general issues):
codex review --base main
Step 2, security deep-dive (if code touches auth, input handling, or APIs):
codex exec "<security prompt from references/prompts.md>"
Step 3, fix findings, then re-review carrying the ledger (see Pattern 5):
codex review --base main
The same shape works per-commit (codex review --commit <SHA>) and mid-development on the working tree (codex review --uncommitted).
Pattern 2: Focused Investigation
Surgical deep-dive on a specific concern (error handling, concurrency, data flow).
codex exec --sandbox read-only \
"You are a senior <DOMAIN> engineer. Analyze <CONCERN> in the changes
between main and HEAD. For each issue: cite file and line, explain the
risk, suggest a concrete fix. Confidence threshold: 0.7."
Pattern 3: Spec / RFC Review
Reviewing prose (markdown design docs) before code is written.
codex exec -c model_reasoning_effort="xhigh" --sandbox read-only \
"You are a senior staff engineer doing a candid pre-implementation review of
<PATH>. The author wants sharp, unsentimental analysis. For each finding:
severity (BLOCKER / HIGH / MEDIUM / LOW), confidence (>= 0.7 only), location
(file path + section heading), the issue, a concrete fix.
End with a one-paragraph go/no-go verdict."
Pattern 4: Single-File / Focused-Path Review
Review one file or directory rather than a full diff.
codex exec --sandbox read-only \
"Review only <PATH> for <CONCERN>. Skip style and ergonomics.
Return PASS if no real issues; otherwise concise FAIL findings with
file:line evidence."
Pattern 5: Ralph Loop (Implement → Review → Fix)
Iterative quality enforcement. Round 1 is broad and hostile. Every later round carries the ledger: enumerate the prior round's findings verbatim plus the fixes claimed, and ask the reviewer to (a) verify each fix with receipts, (b) hunt bugs the fixes introduced, (c) not re-litigate settled trade-offs. Scope decays per round: broad → blockers-only → convergence check with a one-line contract ("PASS / NEEDS_CHANGES: <one sentence>"). For specs, log rounds in a Review History section of the artifact — the loop's state lives in the artifact, not chat exhaust. Re-review templates are in references/prompts.md.
The budget is convergence, not a count. Keep iterating while each round yields a new confirmed finding or verifies a fix; stop when rounds oscillate or re-litigate. Three rounds is the default expectation, not a wall — a fifth round that catches real bugs is fine, while a third round re-arguing round one is already over budget. This budget governs the loop you drive; inbound bot or human feedback streams get fresh re-triage every round and are never capped.
The fix loop is a scope ratchet. Before touching code after a round: triage blockers vs follow-ups, pre-declare a file budget ("three files unless tests force otherwise"), and treat document-why-not as a legitimate response to absence findings. Blockers require changed-line causality; suggestions may cover nearby risk; pre-existing debt becomes follow-up tasks, not in-loop fixes. Unbounded review-response is how a loop ends up editing 120 files.
Multi-Pass Strategy
Thorough reviews benefit from multiple focused passes rather than one vague pass. Single passes dilute attention across dimensions and produce shallow findings on each. Each pass gets a specific persona and concern domain.
| Pass | Focus | Mode |
|---|---|---|
| Correctness | Bugs, logic, edge cases, race conditions | codex review |
| Security | OWASP Top 10:2025, injection, auth, secrets | codex exec with security prompt |
| Architecture | Coupling, abstractions, API consistency | codex exec with architecture prompt |
| Performance | O(n²), N+1 queries, memory leaks | codex exec with performance prompt |
Run passes sequentially — fixing critical findings between passes — when the diff is changing under review. On a frozen artifact, parallel lens-locked passes (one concern each, explicit non-goals) produce additive non-overlapping findings and finish faster.
Line counts are rough guides; scale passes to risk and surface, not arithmetic:
| Change size | Strategy |
|---|---|
| < 50 lines, single concern | Single codex review |
| 50-300 lines, feature work | codex review + security pass |
| 300+ lines or architecture change | Full 4-pass |
| Security-sensitive (auth, payments, crypto) | Always include security pass |
Consuming the Findings
Reviewer output is input, not orders. Re-verify each finding against ground truth — code, git history, live data — before any edit. Three dispositions, always reported: fix now / intentional-keep with named rationale / can't-verify, flagged to the human. "Verified, no code change" is a legitimate outcome; one session disproved 3 of 4 findings and changed nothing. Argue wrong findings down with receipts, never silently drop them. Two independently-briefed reviewers converging on the same bug upgrades it to confirmed.
Codex's characteristic misses to check first:
| Failure mode | Check |
|---|---|
| Temporal scope | Did it review the commit state the finding claims? |
| Near-name confusion | Is the cited artifact the one actually changed? |
| Invented flags/APIs | Does the suggested flag or function exist? Run --help |
| Stale-at-fix-time | Was the complaint valid at review time but now resolved? |
Close the loop both directions: when a defect class is fixed, fold it into the repo's standing review prompt or CI gate so the next reviewer inherits it. When a reviewer keeps hallucinating the same ghost, fix what reviewers ingest — scrub the stale doc it keeps importing. And seed the next review with prior gotchas from memory; they make a sharp hypothesis list.
Prompt Engineering Heuristics
The non-obvious levers that reliably improve review signal quality:
- Specify what to skip. "Skip formatting, naming style, minor docs gaps" prevents bikeshedding
- Require confidence scores and act only on findings ≥ 0.7
- One domain per pass. Security-only, architecture-only
- Demand a verdict. "Verdict: patch is correct / incorrect" or "go / no-go"
The full brief anatomy (verbatim ask, keystone claim, assumed-passed receipts, anti-sycophancy, no-memory line) and ready-to-use templates are in references/prompts.md.
Anti-Patterns
| Anti-Pattern | Why It Fails | Fix |
|---|---|---|
Bare codex review (no scope flag) |
Hangs or produces blob output | Exactly one scope flag — see the ⚠️ scope rule |
Piping review output to tail -N |
Buffers until EOF; cuts the verdict | Redirect to a file — see the ⚠️ capture rule |
timeout 30 codex review |
Reviews legitimately take 30s–5min | No timeout, or timeout 300 minimum |
| Treating transcript size as the failure signal | A 1MB+ codex exec transcript can be a successful deep dive |
Judge by growth and convergence to a verdict (When the Review Hangs) |
| "Review this code" (no specifics) | Vague, produces bikeshedding | Specific domain prompts with persona |
| Single pass for everything | Context dilution, shallow on every dimension | Multi-pass with one concern per pass |
| Self-review (Claude reviews Claude's code) | Systematic bias, models approve their own patterns | Cross-model: Claude writes, Codex reviews |
| No confidence threshold | Noise floods signal, 0.3 confidence wastes time | Only act on ≥ 0.7 confidence |
| Style comments in review | LLMs default to bikeshedding | "Skip: formatting, naming, minor docs" |
| Re-litigating settled findings across rounds | Over budget regardless of round count | Budget is convergence — stop when rounds oscillate, not at a number |
| Review without project context | Generic advice disconnected from codebase | Run from repo root |
| Recurring reviewer hallucination | The ghost usually lives in a doc reviewers ingest | Scrub the stale doc; don't re-argue it every round |
MCP wrapper around codex |
Unnecessary indirection over a CLI binary | Call codex directly via Bash |
Hardcoding --model / -m / -c model= |
Overrides user config; stale model names | Defer to ~/.codex/config.toml |
| Effort override on routine code review | Wastes tokens, ignores user defaults | -c model_reasoning_effort="xhigh" is for spec review only |
--full-auto for pure review |
Grants write access the review doesn't need | --sandbox read-only for review; --full-auto only when applying fixes |
When Codex Can't Run
The gate is non-fungible. When it can't run (quota, CLI wedge, MCP failure), fall down the ladder with the weaker guarantee named: fresh-context same-model review is the floor, different-family is the premium. Disclose the substitution in the wrap and the PR body, and let the human decide whether to proceed. A blocked review channel never produces a PASS.
What This Skill is NOT
- Not a replacement for human review. Cross-model review catches bugs but can't evaluate product direction or UX.
- Not a linter. Don't use Codex review for formatting or style.
- Not a staleness check. Version and SOTA claims need live primary sources regardless of how many models agreed.
- Not infallible. 5–15% false positive rate is normal. Triage findings (see Consuming the Findings).
- Not for self-approval. The whole point is cross-model validation. Don't use Claude to review Claude's code.
References
For ready-to-use prompt templates, see references/prompts.md.