use-codex

# Use Codex ## Core rule **Codex is a bounded peer reviewer + bounded implementation worker. Claude owns the plan, the prompt file, the audit synthesis, the tests, the commits, and the final answer to the user.** The peer-review use case is the killer one: codex doesn't inherit Claude's session context or rationalizations, so its audit catches what Claude misses. Use it BEFORE shipping anything non-trivial that touches money, auth, webhooks, or migrations. ## When to use vs when to skip | Use codex-cli | Use Claude Agent tool subagent | |---|---| | Independent peer review of a non-trivial diff | Audits where Claude's tool context (existing reads) is already loaded | | "Find bugs the orchestrator missed" pass | Reviews where the deciding rubric is in this codebase's CLAUDE.md only | | Multi-file content writes following an explicit spec (alternative to cursor) | Reasoning that needs to feed back into THIS conversation | | Bulk audit of N files where each can be reviewed in isolation | Tasks where Claude needs to inspect the result mid-flight | | Cross-validation of a fix you're 80% sure is right | Trivial edits — Edit tool is faster | | ≥3 files of writes; saves Claude output tokens | Anything where 30s of Claude time would beat 5min of codex round-trip | **Don't use codex for:** - Small targeted edits (Edit tool is faster) - Live debugging / step-through reasoning (codex sessions don't yield mid-flight) - Anything where you need codex's output to immediately influence your next tool call (it's async-friendly, not sync-friendly) - Tasks that REQUIRE the full Claude conversation context (codex starts cold) ## Available models (ChatGPT Plus auth) These work on `codex login --chatgpt` accounts. Wrong model name returns `{"type":"error","status":400,...,"message":"The 'X' model is not supported when using Codex with a ChatGPT account."}` — misleading; same message for "doesn't exist" and "needs API auth". Sanity-test before long-running specs. **Evidence-backed model picker** (full benchmark-backed analysis at `docs/audits/2026-05-02-cli-model-task-matrix.md`; numbers cite vendor blogs + Simon Willison + spectrumailab + MarkTechPost): | Model | Best for | Key benchmarks | Don't use for | |---|---|---|---| | `gpt-5.5` | **Frontier review** (auth/billing/migrations), reasoning-heavy debugging, terminal/agentic harness work, cybersecurity audits, greenfield architecture | Terminal-Bench 2.0 **82.7% (SOTA)**, GDPval 84.9%, FrontierMath Tier 4 39.6% (~2× Opus 4.7), SWE-Bench Pro 58.6% | Routine work where 5.4 fits — 5.5 doubles in price above 272K input | | `gpt-5.4` | **Default everyday coding**, multi-file edits, native computer use, 1M-context analysis under 272K | SWE-Bench Pro 57.7%, Terminal-Bench 2.0 75.1%, OSWorld-Verified 75.0%, GPQA Diamond 93.0% | Frontier reasoning beyond 272K (price cliff) | | `gpt-5.4-mini` | **Parallel subagent fan-out**, OSWorld/screenshot tasks, bulk small-file audits with short context | OSWorld 72.1% (near full 5.4's 75.0%), τ2-bench telecom 93.4% | **Long-context retrieval — MRCR v2 8-needle 64K-128K collapses to 47.7% vs 86.0% on full 5.4** | | `gpt-5.3-codex-spark` | **Ultra-fast coding** (slot 4 in the picker): real-time iteration, single-file tweaks, CI/CD codex-exec batches at 1000+ tps. Also the `gpt-5.5`-exhausted fallback (separate capacity) | Vendor claims Terminal-Bench 77.3% parity with the retired 5.3-codex; **independent re-runs measure ~58.4% — 19-point gap** | **NEVER for hard reasoning.** Plus/Team users may see CLI silently route to default — verify with `/status`, not `/model`. | | ~~`gpt-5.3-codex`~~ **DROPPED from picker (2026-07-01)** | (was: long-horizon agent loops, terminal-heavy) — the non-spark coding variant; probe before use (may `400`) | Terminal-Bench 2.0 77.3%, SWE-Lancer IC Diamond 81.4%, Cybersecurity CTF 77.6% | New work — gone from picker; use `gpt-5.3-codex-spark` or `gpt-5.4` | | ~~`gpt-5.2`~~ **DROPPED from picker (2026-07-01)** | (was: multi-day agent loops, input-heavy long-context) — probe before use (may `400`) | SWE-Bench Verified 80.0%, AIME 2025 100%, MRCRv2 8-needle 128K-256K 77.0% | New work — gone from picker; superseded by 5.4 | Default is `gpt-5.5` per `~/.codex/config.toml`. Always specify `-m` explicitly when scripting — don't rely on the default. **Model-name precision:** `gpt-5.3-spark` does NOT exist; the real name is `gpt-5.3-codex-spark`. The full canonical IDs per OpenAI API docs may also include the alias `gpt-5.3` for the codex variant. **Canonical `-m` model IDs (verbatim from the `codex` `/model` picker, 2026-07-01):** ``` 1. gpt-5.5 (current/default) Frontier model for complex coding, research, and real-world work. 2. gpt-5.4 Strong model for everyday coding. 3. gpt-5.4-mini Small, fast, and cost-efficient model for simpler coding tasks. 4. gpt-5.3-codex-spark Ultra-fast coding model. ``` These 4 strings are the current picker values. **DROPPED from the picker since 2026-05-29** (probe with `codex exec -m <id> --skip-git-repo-check - <<<ping` before relying — may now return `400 ... model is not supported`): `gpt-5.3-codex` (the non-spark coding variant) and `gpt-5.2`. Note `gpt-5.3-codex-spark` moved from slot 5 → slot 4. Any name not routable returns `400 ... model is not supported`. (The benchmark-backed when-to-use picker is the table above; this block is the authoritative name list to copy from.) ### Fallback chain when `gpt-5.5` is maxed out / rate-limited (READ THIS) `gpt-5.5` on ChatGPT Plus auth has a **usage cap that exhausts within a heavy session** — when it does, `codex exec -m gpt-5.5` returns an **empty / zero-byte result** (no error, just nothing). This silently drops the codex seat from a thinktank or audit. Receipt: 2026-05-29 — codex returned empty across ~5 consecutive dispatches in one session while gemini/droid worked, because the 5.5 cap was exhausted. **Detection:** the seat's log is empty / has no `^RECOMMENDED:` (or no substantive output) while sibling seats succeeded. When `gpt-5.5` is exhausted, do NOT just drop the seat — fall back **in order**: 1. **codex with `gpt-5.3-codex-spark`** — same codex CLI, a different (non-5.5) model that draws on separate capacity: `codex exec -m gpt-5.3-codex-spark`. Good for second-opinion audits + bounded review; **NOT for hard multi-step reasoning** (it drifts — see the table). For a frontier-reasoning slot prefer #2. 2. **copilot with `gpt-5.5`** — GitHub Copilot CLI reaches `gpt-5.5` through a SEPARATE quota (Copilot Pro/Business, not the ChatGPT Plus cap), so it keeps the frontier 5.5 perspective alive when codex's 5.5 is dead. Use the `use-copilot` skill: `copilot -p "<prompt>"` (it routes to a strong default; pin 5.5 if the CLI version supports `--model gpt-5.5`). This is the right fallback when the task genuinely needs 5.5-class reasoning. 3. Last resort: drop the codex seat and note the missing voice (still get the other seats) — only if both #1 and #2 are unavailable. In a **thinktank dispatch**, wire this as: try `codex -m gpt-5.5`; if its log comes back empty, re-fire that seat as `copilot -p` (frontier) or `codex -m gpt-5.3-codex-spark` (fast) rather than synthesizing with a silently missing seat. (Cross-ref: `use-copilot` skill; apply the same seat-swap rule in any multi-seat council dispatch.) ## Workflow ```dot digraph codex_workflow { "Identify codex-fittable task" -> "Verify codex auth + model availability"; "Verify codex auth + model availability" -> "Write task spec file"; "Write task spec file" -> "Launch codex exec in background"; "Launch codex exec in background" -> "Continue Claude orchestration"; "Continue Claude orchestration" -> "Wait for codex exit"; "Wait for codex exit" -> "Audit output"; "Audit output" -> "Synthesize into Claude's response"; } ``` ### 1. Verify codex is available + which model ```bash codex --version # 0.128.0 or higher codex login status # "Logged in using ChatGPT" expected cat ~/.codex/config.toml | grep "^model" ``` If `codex` isn't on PATH, the user installs via `npm i -g @openai/codex`; do not attempt to install yourself. ### 2. Write the task spec file in the repo Save at `<repo>/.claude/codex_task_<short-name>.md`. Don't put it in `.tmp/` or anywhere gitignored — the spec should be discoverable in PRs and post-mortems. **If the task is to write a driver script for a long-running remote job:** the spec should require the sub-agent to validate environment prerequisites (dependency versions, credentials, disk) BEFORE the main work starts, so the job fails fast at setup rather than deep into an expensive run. If you maintain a job-setup/verification convention, cite it in the spec. Spec shape (parallel to use-cursor; codex tolerates more conversational tone): ```markdown # codex task: <one-line objective> You are running as `codex exec` in non-interactive mode against the `<branch>` branch of `<repo>` at `<absolute path>`. <Constraint sentence — e.g. "Do not modify any code; produce a markdown audit report."> ## Context (what the orchestrator believes is true) - Recent shipping history relevant to this task - F* finding numbers + what they claim to fix - Tier classifications (CRITICAL / HIGH / MEDIUM / LOW) ## Files to review (focus your attention here) ``` path/to/file.py # what changed, why it matters ... ``` ## What to look for (severity-ranked checklist of bug classes) ## Output structure (exact markdown shape for the audit doc, with headers + tables) ## Constraints - Do NOT modify code (audit only) OR Do NOT push (just edit) - Do NOT git add/commit/push - Use model X end-to-end - Working dir is <path> - If file > 500 lines, focus on diff regions via `git log -p -- <file>` ## Done criteria Print: `[codex-audit] DONE <scope> critical=N high=N medium=N low=N file=<path>` Then exit. Do NOT continue to interactive mode. ``` Be explicit. Codex's exec mode is competent but cold-starts every session, so spec MUST contain everything it needs (no "as we discussed earlier"). Inline the orchestrator's existing claims so codex can VALIDATE rather than re-derive. ### 3. Launch codex exec in the background **ROUTE THROUGH THE HEADLESS WRAPPER** (2026-05-13 fix). The wrapper at a local headless wrapper script temporarily renames both Superpowers entrypoints (any auto-loading skill/plugin junctions codex would otherwise pick up) OFF for the lifetime of `codex exec`, then restores them via try/finally — so the global skill scan can't auto-load using-superpowers/brainstorming/TDD on every headless dispatch and hijack the response. The inline skill-bypass preamble in the spec is now defense-in-depth only; the wrapper is the load-bearing fix. The wrapper also injects `--ignore-user-config` by default so OAuth MCP servers from `~/.codex/config.toml` cannot hang a headless run with `rmcp::transport::worker: Auth(TokenRefreshFailed)`. If the Codex seat truly needs MCP/user config, pass wrapper-only flag `--with-user-config` and refresh the specific OAuth server first with `codex mcp login <server>`. ```bash mkdir -p /tmp/codex_logs cd <workspace>/REPO # ← REQUIRED on Windows; do NOT use --cd flag # WSL path → Windows path for powershell.exe WIN_REPO=$(pwd | sed 's#^/c/#C:/#; s#/mnt/c/#C:/#; s#/#\\#g') # PREFER the codex dispatch wrapper (v2 2026-05-13) over the raw headless wrapper # for spec-from-file dispatches from WSL. Three Windows-specific failure modes # the raw wrapper hits on multi-KB markdown specs: # # 1. `< spec.md` stdin-redirect through `nohup powershell.exe -File` does NOT # propagate stdin to codex — codex reads zero bytes then exits cleanly, # log shows only the prompt echo with no assistant turn. # 2. The wrapper's `--ignore-user-config` injection (the MCP-hang defense) # strips `model_reasoning_effort` from ~/.codex/config.toml — codex runs # at reasoning=none and emits zero tool calls. Must explicitly pass # `-c 'model_reasoning_effort="high"'`. # 3. Get-Content -Raw → positional prompt arg makes PowerShell native-exe # arg-passing split on whitespace; any markdown hyphenated token (e.g. # `log-frequency` in a docstring) gets interpreted as a clap-rs flag. # # the codex dispatch wrapper sidesteps all three: Get-Content -Raw -Encoding UTF8, # mirrors auto-loading skill junction handling inline (mutex + rename + try/finally), # explicit reasoning_effort, and pipes prompt via `$prompt | & codex -` (the # `-` is a string literal positional from inside PowerShell, so the wrapper- # rejection of leading-dash doesn't apply). # # Source: `a local codex dispatch wrapper` WIN_SPEC="<workspace>/REPO/.claude/codex_task_<name>.md" WIN_REPO="<workspace>/REPO" nohup powershell.exe -ExecutionPolicy Bypass \ -File 'a local codex dispatch wrapper' \ -SpecPath "$WIN_SPEC" \ -WorkDir "$WIN_REPO" \ -Model gpt-5.5 \ -ReasoningEffort high \ > /tmp/codex_logs/<name>.log 2>&1 & echo $! > /tmp/codex_logs/<name>.pid # If you have a one-shot bounded prompt (no spec file), the raw wrapper still # works because the prompt is the positional arg (no stdin handling needed): # # powershell.exe -ExecutionPolicy Bypass \ # -File a local codex headless wrapper \ # -m gpt-5.5 \ # -c 'model_reasoning_effort="high"' \ # --skip-git-repo-check \ # "Your one-line prompt here" # Sanity-verify the process is alive past startup (catches the silent-die # failure mode where codex exits in <1s with the os-error-2 bug): sleep 3 if kill -0 $(cat /tmp/codex_logs/<name>.pid) 2>/dev/null; then echo "alive — workdir line in log:" grep "^workdir:" /tmp/codex_logs/<name>.log else echo "DIED AT STARTUP — check log:" cat /tmp/codex_logs/<name>.log fi ``` Flags: - `-m <model>` — pin the model explicitly (don't trust default) - `--cd <abs-path>` — set working dir; codex defaults to its own launch dir (often a different project!). **Gotcha (proven 2026-05-02):** when launched via bash+nohup on Windows, `--cd C:\\dev\\projects\\REPO` (backslash-escaped) causes codex to die at startup with `Error: The system cannot find the file specified. (os error 2)` and ZERO log output beyond that. Workarounds (in priority order): (a) `cd <repo>` in the launching shell first and OMIT `--cd` entirely (codex inherits pwd); (b) use forward slashes `--cd <workspace>/REPO`; (c) use the cygpath-style `--cd <workspace>/...` (UNTESTED). The pwd-inheritance approach is the most reliable. - `--skip-git-repo-check` — for cases where the spec dir isn't the repo root - `--dangerously-bypass-approvals-and-sandbox` — required for unattended background execution; safe ONLY because the spec forbids destructive ops (no commit/push, audit-only). Do NOT pass this for write-mode tasks unless you fully trust the spec - `- < .claude/...md` — read prompt from stdin (cleaner than -p inline arg) The Bash tool's `run_in_background: true` parameter is an alternative when you want Claude to be notified on completion via the task-notification channel. **Note: codex CLI does NOT need WSL on Windows** (unlike cursor-agent). It runs natively from bash, PowerShell, or cmd. Windows path separators in `--cd` need double-escaped backslashes (`C:\\dev\\...`) when invoked from bash. ### 4. Continue Claude orchestration