Codex

Codex as a Thinking Partner

codex exec provides independent perspective from a separate AI agent. Runs locally, reads codebase, returns analysis to stdout.

Shell prerequisite: the recipes below use bash features (/tmp/ paths, heredocs, cygpath). Claude Code ships with bash on every platform (native on Linux/macOS, Git Bash on Windows) so this is usually a non-issue — but if you're running Codex commands from native Windows cmd or PowerShell outside Claude Code, adapt the syntax.

When to Use Codex

• Exploring design space — want alternatives before committing → Brainstorm
• Have a plan or design — want weaknesses flagged (failure modes + over-engineering + missed simplifications) before investing implementation time → Red-team
• Change feels heavier than the problem it solves — new abstraction, config surface, extra layer, or process step you suspect does not earn its keep → Red-team, with the question aimed at what to cut
• Bug where local reasoning is stuck — obvious hypotheses ruled out, OR unfamiliar stack where causes/instrumentation/repro are non-obvious → Debug
• Plan spans multiple subsystems or has non-trivial step ordering — want sequencing, gap, rollback review → Plan Review
• Have a diff or report — want factual claims verified, regressions found, or mismatch with the ticket/spec caught (prose optional) → Diff Review
• Ticket is prose with implicit requirements, or legacy code lacks clear contracts — need concrete acceptance checklist before coding → Spec Extraction
• Shipping risky change — schema update, API change, migration with operational impact → Rollout/Rollback
• Want independent tradeoff evaluation to pick among a handful of concrete approaches → Compare/Decide
• Want regression cases or edge conditions — whether before coding a risky refactor or after finishing an implementation → Test Gaps
• Careful reading leaves meaningful parts unclear — undocumented, complex algorithms, legacy code where the non-obvious logic needs surfacing → Explain
• Production incident or CI failure — have logs/traces, need root cause → Post-mortem
• Security-sensitive design or diff, OR obvious attack vectors exhausted in ongoing testing — auth, permissions, tenant boundaries, file upload, parser, secrets, untrusted input → Attack Surface
• Exhausted known hypotheses — all leads investigated, dead-ends recorded, want external model to find what pipeline systematically missed → Exhausted Hypotheses

When NOT to Use Codex

• Single-file mechanical edit (typo, rename, one-import change) with no new concepts
• Answer is already in context
• Conversation is active back-and-forth, or user indicated urgency — 1–5 min wait would break the flow
• Already used Codex (or Antigravity) for this question this session, OR you're about to fire both on the same prompt — retry narrower prompt, or escalate to user
• No specific artifact or concrete question — just a topic or area to "think about"
• Prompt would contain secrets, credentials, or PII
• Question is about Claude Code internals (hooks, skills, MCP, settings) — /claude-code-docs knows, external CLIs don't
• Answer lives in library/tool docs — WebFetch, Context7, or man is cheaper
• Missing local facts — reproduce the issue, inspect logs, run rg/git/blame, or ask user for clarification — before outsourcing reasoning
• Decision depends on product priority, compliance, or release timing not in my context — ask the user (who owns this) first

Precedence

When multiple bullets match a single prompt:

• WNTU wins over WTU. If any When NOT to Use bullet matches, don't fire — even if a When to Use bullet also matches. If unsure, ask the user ("I'd skip Codex here because X; proceed anyway?") rather than firing.
• Among WTU, pick the most specific. "Shipping risky change" over "Have a plan or design." "Security-sensitive diff" over "Have a diff or report." The more specific mode carries more relevant context.
• Among WNTU, privacy beats cost. Privacy/confidentiality skips are hard (never fire). Session/cost skips are soft (can escalate to user). If a prompt would contain secrets, that overrides every other consideration.

Execution Reference

Basic Invocation

# Short prompt as argument
codex exec --ephemeral -s read-only "<prompt>" < /dev/null

# Long prompt via stdin (preferred for multi-line)
codex exec --ephemeral -s read-only <<'PROMPT'
Your long prompt here...
PROMPT

A prompt argument and piped stdin now combine: both reach Codex, so a piped artifact is no longer lost when an argument is also given. Piping remains the safer route for anything long or multi-line, since a shell argument has to survive quoting.

Close stdin when the prompt is an argument. Because codex exec reads stdin as well, a run whose stdin stays open can block on it and finish having written nothing, leaving an empty -o file and Reading additional input from stdin... as the only trace. Append < /dev/null to any argument-only invocation, background ones especially.

What an unquoted heredoc expands: <<PROMPT expands $vars, $(...) and backticks that you type in the heredoc source. It does not rescan what a command substitution inserts, so backticks, $vars and even a line equal to the delimiter word inside $(cat file) output all reach Codex intact. Quote the delimiter (<<'PROMPT') when the prompt you typed contains shell metacharacters you want left alone. Ways to send a long artifact:

• Pipe pattern (preferred): cat file | codex exec --ephemeral -s read-only
• Temp file pattern: write full prompt to temp file, then cat tmpfile | codex exec --ephemeral -s read-only
• Quoted heredoc: <<'PROMPT' prevents every expansion, so no $(...) interpolation is possible inside it

Always pass -s. With no -s, codex exec runs workspace-write, which a review never needs. The exception is codex exec resume, which inherits the original session's sandbox and rejects -s outright.

Windows sandbox note: some older Codex builds could not launch the Windows sandbox helper, so every sandboxed tool call died with windows sandbox: spawn setup refresh or OS error 740 before PowerShell started (openai/codex#25362, since closed). The failure no longer reproduces on a current build: file reads under -s read-only and an in-workspace write under -s workspace-write both succeeded with no such warning. If you do hit those log lines, update the CLI first. On an install you cannot update, embed the needed file contents in the prompt and run -s read-only, or add -c 'windows.sandbox="unelevated"' for the modes where Codex must inspect files itself (that backend cannot enforce deny-read rules or split writable-root sets, so avoid it for runs that depend on those).

Keep including in prompts: "Use PowerShell-compatible commands (Get-Content, Select-String). Codex's internal shell on Windows is PowerShell, not Git Bash."

Key Flags

Model Selection

Leave the model unset so the CLI default and ~/.codex/config.toml apply, and reach for -m only when the user asks for a specific model.

Codex currently defaults to Astra (gpt-6-astra). Run Astra at medium reasoning effort for now: that is what the local config should carry, and -c model_reasoning_effort=medium pins it for one run if the config says otherwise.

Name the model you used in any summary you present, so the user can tell what produced the analysis.

Code Review

Prefer codex exec review over codex review — supports full flag surface (-m, --json, -o). Top-level codex review works but has fewer options:

codex exec review --ephemeral -s read-only --uncommitted -o c:/tmp/codex-review.txt < /dev/null  # Review working tree changes
codex exec review --ephemeral -s read-only --base main -o c:/tmp/codex-review.txt < /dev/null    # Review changes against a branch
codex exec review --ephemeral -s read-only --commit abc123 -o c:/tmp/codex-review.txt < /dev/null # Review a specific commit
codex exec review --ephemeral -s read-only "Focus on security" -o c:/tmp/codex-review.txt < /dev/null # Custom review instructions

Resuming a Conversation

The CLI carries multi-round work by itself, so no wrapper is needed. Capture the id, then resume with it:

ERR=c:/tmp/codex-<slug>.err
codex exec -s read-only -C "$(pwd)" -o c:/tmp/codex-<slug>-r1.txt "<round 1 prompt>" 2>"$ERR" < /dev/null
SID=$(sed -n 's/^session id: //p' "$ERR" | tr -d '\r' | head -1)

codex exec resume "$SID" -o c:/tmp/codex-<slug>-r2.txt "<round 2 prompt>" < /dev/null

Keep that stderr file until the round is validated. A run can print its header, capture a usable id, then fail with an empty -o file, and stderr is the only place saying why. One observed cause is a plain account usage limit, reported there and nowhere else.

Resuming restores the prior context, so the model still recalls round 1 without you re-sending it, and the round bills far fewer tokens than a fresh run (493 against roughly 20k in one measured pair). Send the artifact again only when the artifact itself changed.

Resume by UUID, and check the header. The identifier decides how a miss behaves. An unknown UUID fails loudly (no rollout found for thread id <uuid>). Anything that does not parse as a UUID is treated as a thread name, and an unknown name does not fail: it silently starts a new conversation and answers as if fresh. The tell is the header, which reports a session id other than the one you asked for, so compare the two before trusting a resumed answer.

Names come from the interactive TUI anyway, so a headless workflow should carry the UUID: -c thread_name=... on codex exec does not make a name resolvable to resume.

Two more limits. A resumed run inherits the original session's sandbox and working directory and accepts no -s of its own. --last resumes the most recent session without needing an id, and can therefore land in a wider sandbox than the current task wants. And --ephemeral does not persist a session, so leave it off any run you intend to resume.

For review modes, prefer a fresh one-shot over a resume. Asking a model to attack its own prior reasoning is what a resumed review does, and Convergence Mode below carries findings forward in the prompt instead.

Mode-to-Sandbox Table

Rows with -C let Codex inspect the repository itself; git log, git diff and file reads all run under -s read-only, so none of these modes needs write access. Add -C "$(pwd)" to any other row when its material lives in a repo: a reviewer that can only see the excerpt you pasted cannot judge it against the code around it, or find the related problem the excerpt left out.

Windows caveat: on an old build that logs windows sandbox: spawn setup refresh, every row here breaks. See the Windows sandbox note above.

Execution Rules

• Set generous Bash timeout, or omit when using run_in_background: true
• Use run_in_background: true so user is not blocked waiting
• On any run whose analysis you will read back, use -o <temp>/codex-<descriptive-slug>.txt to write final analysis to clean file, where <temp> is c:/tmp on Windows (create once via mkdir -p c:/tmp) and /tmp on Linux/macOS. Do NOT use /tmp/... for the -o path on Windows — Bash in Git Bash resolves it to %TEMP% (the -o path is translated by Git Bash before Codex receives it) and the write succeeds, but Claude's Read tool treats the path literally and fails with File does not exist when you try to read the output back. Using c:/tmp/... on Windows makes both Codex's write and Claude's Read resolve to the same Windows-native location. Separates output from shell noise. Read the -o file for analysis, not the background task output file.
• When running in background, also use 2>&1 to capture stderr — background output file serves as debug log if -o file is empty or missing. Skip it when stderr is already going to its own file, as in the resume recipe: 2>&1 there would swallow the session id line the capture depends on
• Add --skip-git-repo-check when running outside a git repository
• Cleanup: after reading -o file, delete it (rm -f <temp>/codex-<slug>.txt, where <temp> is the same c:/tmp (Windows) / /tmp (Linux/macOS) location used for the -o write above). Temp files accumulate otherwise.
• Wait for completion: NEVER read or delete -o file until you receive <task-notification> confirming background task completed. File may be 0 bytes or missing before Codex finishes — does NOT mean it failed. Premature reads produce false "empty output" conclusions; premature deletes destroy results the process is about to write.
• Re-launch safety: if re-launching a Codex invocation, use a DIFFERENT output slug (e.g., <temp>/codex-redteam-auth-v2.txt). Never reuse -o path of still-running or recently-launched invocation — two processes will collide on output file.
• Chase down all output: if -o file is empty but task completed successfully, check background task output file for actual analysis or paths where Codex wrote results. Never skip or dismiss review output because it ended up somewhere unexpected.
• Passing -o paths to subagents: a subagent has the same Windows /tmp/ blind spot as the main-session Read tool, so follow the <temp> rule above and c:/tmp/codex-<slug>.txt resolves natively. For a legacy /tmp/... output, either inline the content into the subagent prompt (up to ~50KB) or pass $(cygpath -w /tmp/codex-<slug>.txt).

Base Prompt Template

One unified template. Adapt per mode by filling relevant fields and appending mode-specific instruction.

Mode: {brainstorm|red-team|debug|plan-review|diff-review|spec-extraction|rollout-rollback|compare-decide|test-gaps|explain|post-mortem|attack-surface|exhausted-hypotheses}
Question: {what you want Codex to decide or critique}
Context:
{relevant plan, diff, logs, or summary — use the smallest useful artifact}
Current belief: {your current approach or hypothesis, if any}
Constraints: {time, risk, compatibility, scope — omit if none}

Return:
- verdict or recommendation
- top risks / hypotheses / objections
- missing evidence
- concrete next step

Be direct and concrete. If evidence is insufficient, say exactly what is missing.

Simplicity bar: prefer deletion, inlining, or code that already exists. For any recommendation that adds a layer, wrapper, config knob, flag, interface, or file, name the reachable failure or the stated requirement that the smaller option cannot cover, and drop the recommendation if you cannot. Do not propose abstractions with a single caller or a single implementation, or generality for requirements nobody has stated. Keep checks at trust and system boundaries. If the artifact is already heavier than its stated scope, say that first.

Response style: compress prose. Drop fillers, hedges, connectives unless load-bearing. Prefer short active sentences. Keep verbatim: code blocks, diffs, file:line citations, log entries, numbers, names, paths, quoted context, and tables (headers, cells, and structure). Never compress code. If compression would obscure a finding, write normal prose.

Smallest useful artifact rule: prefer the smallest useful artifact — only include what Codex needs to form a judgment.

Omit empty sections rather than forcing every field. The simplicity bar is the exception: send it in every prompt, in every mode, and trim other fields before it. A review left to its own defaults answers with additions (more validation, more layers, more configuration, more phases), which is the bias the paragraph cancels.

Mode-Specific Additions

Append one of these to the base template:

• Brainstorm: "Generate 3-5 alternatives with tradeoffs. Include at least one option that solves the problem with less machinery than the current approach. End with a recommendation and why."
• Red-team: "Find weaknesses. Structure response under two explicit headings, each given equal scrutiny (their lengths can differ):

Breakage

Failure modes, edge cases, wrong assumptions. What could break. Attack assumptions. Give the strongest counterargument.

Prioritize the classes of failure that are expensive, dangerous, or hard to detect:

• auth, permissions, tenant isolation, and trust boundaries
• data loss, corruption, duplication, and irreversible state changes
• rollback safety, retries, partial failure, and idempotency gaps
• race conditions, ordering assumptions, stale state, and re-entrancy
• empty-state, null, timeout, and degraded-dependency behavior
• version skew, schema drift, migration hazards, and compatibility regressions
• observability gaps that would hide failure or make recovery harder

Default to skepticism. Do not give credit for good intent, partial fixes, or likely follow-up work. If a code path only works on the happy path AND the sad path is reachable from an untrusted caller or a realistic operational failure, treat that as a real weakness. Prefer depth over breadth: one fully-evidenced finding beats three speculative ones.

Do NOT flag as Breakage:

• edge cases unless reachable through a less-trusted data path or realistic operational failure
• missing validation at private call sites only when every caller already preserves the invariant across the full data path
• missing error handling only for invariants guaranteed without runtime data, casts/assertions, peer/schema skew, or cardinality assumptions
• "could in theory fail" without naming the caller, input, and concrete failure
• missing retries/fallbacks only for deterministic in-process work; I/O, scheduling, and cross-process effects can fail operationally

Prefer 'no finding' over a speculative finding. Every fix you propose must be the smallest one that closes the hole. Where the fix would ADD defensive code, first ask whether removing code prevents the same defect; where it would add a layer, flag, or abstraction, say what the one-line version costs and why it is insufficient.

Simplifications

Over-engineering and missed reductions. Hunt for:

• abstractions, interfaces, factories, registries, or base classes with a single caller or a single implementation
• wrappers and indirection that only forward arguments
• configuration, flags, and options nobody sets, and defaults nobody overrides
• generality built for requirements that are not stated anywhere
• validation, error taxonomies, or retries around inputs the call path or the type system already constrains
• caching, bookkeeping, or duplicated state that recomputation would make unnecessary
• ceremony around the change: scaffolding files, docs restating the code, tests asserting mocks or framework behavior
• parallel copies of one fact (constants, schemas, docs) where everything could read one source

For each: what to cut, merge, or flatten, why that is safe, expected impact. Biggest cut first. If the design is sound but heavier than the problem it solves, say so as the verdict, even when Breakage is empty. If you find nothing to cut, write 'nothing to cut' plus one sentence of why, and do not pad the section. Do NOT strip defensive code at system boundaries, WHY comments, or anything whose removal sacrifices clarity for brevity.

Do not agree just to be agreeable. Do not pad either heading to look balanced."

• Debug: "Rank hypotheses by likelihood. Suggest the cheapest diagnostic step for each. Focus on hypotheses I am likely to have missed."
• Plan Review: "Find missing steps, sequencing issues, rollback gaps, and operational risks. Also flag steps that could be dropped, merged, or handled by something the codebase already does. Cite file names and line numbers when pointing out issues."
• Diff Review: "For each claim, verify from code or docs. Flag assumptions stated as facts. Check for stale information. Flag machinery the diff adds that its stated goal does not require. Include a blast-radius note: touched surfaces, downstream callers, and any migration or test surface the diff pulls into scope."
• Spec Extraction: "Extract invariants, edge cases, non-goals, and a test checklist. Output a concrete acceptance criteria list, not prose. Mark which criteria the source states and which you inferred."
• Rollout/Rollback: "Start from the simplest safe rollout and say whether a straight deploy covers this one. Add a phase, feature flag, or observability check only where you can name the failure it catches that a straight deploy would not. Give the rollback plan and identify the point of no return. Map the blast radius up front: touched surfaces, downstream callers, migrations, and operational impact."
• Compare/Decide: "Evaluate each option against the stated constraints. For each, list strengths, weaknesses, and hidden risks. Add the smallest option that still meets the constraints, even if nobody listed it. Pick one and explain why."
• Test Gaps: "Identify untested edge cases, missing error paths, and boundary conditions. Output a concrete test checklist, not general advice. Leave out tests that would only assert mock behavior or invariants the types already guarantee. Map the blast radius first — touched functions, downstream callers, and the test surface that should cover them — so the checklist reaches beyond the directly changed code."
• Explain: "Read the code and explain what it does, why it's structured this way, and what the non-obvious parts are. Flag anything that looks like a bug or anti-pattern."
• Post-mortem: "Analyze the timeline, identify the root cause, distinguish contributing factors from the trigger, and suggest preventive measures. Cite specific log entries as evidence."
• Attack Surface: "Identify overlooked attack vectors, underexplored entry points, and non-obvious vulnerability classes for this target. Consider logic flaws, trust boundaries, race conditions, and chained weaknesses — not just OWASP top 10. Prioritize by likelihood and impact. For each finding, note the blast radius: the tenant isolation broken and the data or actions exposed."
• Exhausted Hypotheses: "You are reviewing a codebase that has already been through extensive security analysis. All obvious and semi-obvious hypotheses have been investigated. Your job is to find what was missed — not what was already tried. Generate 5-10 novel vulnerability hypotheses NOT listed in the dead-ends or existing hypotheses. For each: (1) exact file:line, (2) attack scenario with concrete steps, (3) why a systematic review pipeline would miss this, (4) impact if exploitable, (5) what makes this esoteric or non-obvious."

Shell Pipeline Recipes

Ready-made patterns for common workflows:

# -o paths below use /tmp (Linux/macOS); on Windows use c:/tmp instead, per the
# <temp> convention in Execution Rules (Claude's Read tool can't resolve /tmp on Windows).

# Review staged changes adversarially
codex exec --ephemeral -s read-only -C "$(pwd)" -o /tmp/codex-red-team.txt <<PROMPT
Mode: red-team
Question: Find the most likely regressions in this diff.
Context:
$(git diff --staged)
Current belief: {your hypothesis, so it can be attacked}
Return: findings under two headings, Breakage and Simplifications, each given equal scrutiny.
Simplicity bar: prefer deletion or inlining; for any addition, name the failure the smaller option cannot cover.
PROMPT

Note: recipes use unquoted <<PROMPT (not <<'PROMPT') so $(...) command substitutions expand inside heredoc.

Claude/Codex Collaboration Loop

Sequence for best results:

1. Claude gathers facts locally — grep, read files, run tests, collect logs
2. Claude sends focused artifact + question to Codex — smallest useful excerpt, not raw dumps
3. Codex synthesizes, critiques, or generates options — independent analysis
4. Claude validates Codex's output against actual codebase — check cited files exist, claims are accurate
5. Claude presents synthesis to user — both perspectives if disagreement exists

Never delegate raw repo exploration to Codex when Claude can do it faster with local tools. Codex adds value through independent reasoning, not file reading.

Convergence Mode (iterative review)

Some review tasks converge rather than conclude. When reviewing an evolving artifact — a spec, plan, or design that will go through multiple revisions — prefer running Codex in a convergence loop: repeat review → fix → re-review until the reviewer gives an affirmative verdict, the user stops, or scope drift is detected.

When to use

• Reviewing an iterating artifact (spec, plan, design) that likely needs several revisions.
• User has signaled iterative review; one-shot is insufficient.
• There is time for multiple rounds (2-5 min per round typical; larger artifacts or deep analysis can run longer).

Loop shape

1. Invoke Codex with the full artifact and a clear Question:.
2. Parse findings; summarize to the user; propose fixes.
3. Gate 1 — apply fixes. Ask yes-all / per-finding / skip. Apply as selected.
4. Gate 2 — continue or stop. Re-state the original one-sentence brief in your prompt. Ask continue / stop / switch-mode. If continue, loop to (1).
5. Terminate when the reviewer's verdict_text is affirmative for the mode ("approve" / "no redesign-class problem" / "no regressions" for red-team; "Yes." / "executable as-is" for compare-decide; "READY TO EXECUTE" / "approve" / "ready" for plan-review; "no regressions" / "approve" for diff-review) AND no findings remain open; OR user stops; OR scope drift detected (see below).

Across-round prompt construction

• Round 1: full artifact + question + (if using) structured directive.
• Round N > 1: also include a Previously identified findings: block listing prior findings (title, severity, status: addressed / skipped). This gives the reviewer drift-detection context and prevents re-finding the same issues by luck.
• After context compaction: if the user resumes a cycle that lost context, they paste the current findings list back into the conversation. No persistent on-disk state is required; findings fit in the conversation.

Anti-pattern: the scope-drift spiral

The convergence loop is excellent at deepening a design and terrible at questioning its direction. Each round's findings are individually valid, but the cumulative effect can pull the artifact into a regime the user never asked for. Signs of drift:

• The artifact has grown by hundreds of lines per round.
• New rounds are finding issues in fixes you added in prior rounds rather than in the original artifact.
• Routine "yes-all" user responses with no pushback — either the user trusts the process (fine) or you're not surfacing options honestly (not fine).
• Codex Simplifications findings get absorbed as refactors ("merge X and Y") rather than used as stop signals ("did we need X or Y in the first place?").
• Per-finding drift detection (exact-title / evidence-overlap) shows zero drift — because brief-level drift does not show up as finding recurrence.

What to do:

1. At every Gate 2, re-state the original one-sentence brief in your presentation. Don't just ask "continue?" — ask "given the original goal, does this next round of fixes make sense?"
2. Weight Simplifications at least as heavily as Breakage. The default bias is toward addition; correct for it by actively looking for "remove this" opportunities.
3. Monitor artifact size growth. If a round grows the artifact by >50%, that is a signal to stop and re-confirm scope before continuing.
4. Treat routine user "yes-all" as a warning, not a go-ahead. Add friction on purpose. Present simplify-first and remove-this options alongside add-machinery options.

Handling Output

• Never relay raw Codex output to user. Extract disagreements, key risks, best next step.
• If Codex disagrees with your approach, present both perspectives and let user decide.
• If Codex finds clear errors, fix them before presenting. Flag debatable ones for user.
• Weigh add-machinery findings before relaying. For any finding that adds code, config, or process, state the smallest version of the fix and whether removing something closes the same hole. Attribute any smaller alternative you worked out yourself to yourself — the reviewer did not say it, and the fidelity rules below forbid presenting it as though it did. Present a finding whose only payoff is ceremony as optional, and label it as such. If a review comes back with additions and no cuts at all, say so; a finding count is not a verdict.
• Structure alternatives as comparison table when presenting multiple options.
• Retry rule: if Codex returns generic advice, rerun with narrower question and better-scoped artifact. Do not retry more than once.

Summarization Fidelity

Codex summaries are a recurring source of QA errors. The failure mode is compression-with-punch: turning measured verbs into rhetorical ones and skimming past inline prose citations. Three rules, ordered by frequency of violation:

1. Quote evaluative language verbatim, never paraphrase it

Codex's verbs are calibrated. "I disagree" ≠ "rejects". "too narrow" ≠ "misses an entire class". "targets the pattern class" ≠ "highest-leverage". If Codex used a measured verb, quote it — do not substitute a stronger rhetorical synonym when compressing.

• Bad: "Codex rejects the plan in 7 of 7 dimensions."
• Good: Codex restructures 6 phases and says "I disagree with the belief that Phase 1 is highest-leverage" on the 7th.

2. Do not add explanatory bridges that are not in source

When Codex makes a bare claim ("X is too narrow") without giving an example, do not add a parenthetical that supplies one from elsewhere in your context. The connection between two true facts is fabrication if Codex did not make it.

• Bad: "Column 3 is too narrow (misses the platform-failure class — the InboundNonce+UsedHash bundle died on this)"
• Good: "Column 3 is too narrow." [no example given by Codex]

3. Count inline citations in prose, not just bullet lists

Codex sometimes cites file:line inside an explanatory sentence rather than in a bullet. When counting call sites or references, scan the prose, not just the list markers. Undercounts happen when you enumerate bullets and miss inline citations.

Mandatory QA for high-stakes modes

After summarizing Codex output for plan-review, red-team, diff-review, exhausted-hypotheses, or attack-surface modes, run the reviewer agent on your summary before presenting it to the user. These modes produce the longest outputs and the highest-consequence summaries, and they are where summarization errors concentrate. The QA step is non-optional for them.

Low-stakes modes (brainstorm, spec-extraction, explain, test-gaps, compare-decide, debug, post-mortem, rollout-rollback) do not require the QA step — rely on the three rules above.

Short-output exception: If the Codex output is under ~200 words AND contains no bullet lists, numbered findings, or file:line citations, the mandatory QA step can be skipped. The three failure modes all need more surface area than that to happen.

Reviewer-unavailable fallback: If the reviewer agent is unavailable (tool failure, subagent budget exhausted), fall back to self-review against the three rules: re-read the source Codex output, quote every evaluative verb verbatim in the summary, and count inline citations in prose as well as in bullets. Flag the fallback explicitly in the presented summary: "(self-reviewed against fidelity rules — no reviewer agent pass)".

The QA check runs against the source Codex output and your summary, flagging strength amplification, fabricated bridges, undercounts, and line-number hallucinations. Errors caught in QA must be corrected in the summary before presentation, not annotated afterward.

Anti-Patterns

Do NOT do these when prompting Codex:

• Vague prompts — "What do you think?" or "Any ideas?" → Always give constraints, desired output shape, concrete question
• Dumping entire files — sending 2000 lines when 80 lines of relevant diff would do → Use smallest useful artifact
• Asking Codex to execute — Codex adds value through independent reasoning, not running commands → Use for analysis and critique
• Skipping "Current belief" (in red-team/debug modes) — Codex can't challenge what it doesn't know you believe → State your hypothesis so it can attack it. Brainstorm mode is fine without one.
• Trusting without validating — Codex may hallucinate file names, functions, or line numbers → Always verify cited artifacts against actual codebase

Troubleshooting