---
name: codex-first
description: "Claude Code work routing: delegate hands-on work to Codex under the native-Claude model gate. Keep specification, judgment, and verification in Claude; prefer isolated Codex-backed autoreview."
---

# Codex First

## Launch flags — read first, copy verbatim

Default every Codex worker, **fresh or resumed**, to **GPT-6.1 Sol, high
reasoning, Ultrafast service tier** (`service_tier="ultrafast"`). Pass all three
settings unless the user requests an override.

```bash
# fresh
codex exec --yolo -C "$WT" \
  -m gpt-6.1-sol -c 'model_reasoning_effort="high"' \
  --enable fast_mode -c 'service_tier="ultrafast"' \
  -c 'model_auto_compact_token_limit=260000' \
  -o "$OUT" - < "$ORDER"
# resume: pass the same flags again; resume does not inherit them
codex exec resume "$SID" --dangerously-bypass-approvals-and-sandbox \
  -m gpt-6.1-sol -c 'model_reasoning_effort="high"' \
  --enable fast_mode -c 'service_tier="ultrafast"' \
  -c 'model_auto_compact_token_limit=260000' -o "$OUT" -
```

- Ultrafast has a context ceiling (measured 2026-10-13, direct Responses probes, gpt-6.1-sol +
  gpt-6-astra): served `ultrafast` up to ~282k prompt tokens, flaky at 288–294k, `fast` at
  ≥300k — silently, HTTP 200. Config default compacts at 400k, so long workers drift to Fast;
  the 260k compact cap keeps them Ultrafast. Rollouts record only the requested tier; prove the
  served tier with a direct probe (`response.service_tier`).
- Context: workers get the base 500k window. Add `-p sol61-1m` (or `-p astra-1m`) only when the
  order needs a whole-repo context; see `$codex-huge-context`. Those profiles forfeit Ultrafast
  above ~280k.
- Copy all model/reasoning/tier flags into wrappers; override only on user request. Verify launch arguments (`ultrafast` default; requested `fast` is valid).
- For requested Fast reviews, use `--codex-speed fast`.

### Cyber-classifier refusal → Daybreak Red (Peter, 2026-10-15)

Worker stops with `This content was flagged for possible cybersecurity risk` → relaunch or resume
the same order on **Daybreak Red** (Peter: "use daybreak red if you hit a blocker with regular
models"). Don't rephrase to dodge the classifier or hop between regular models.

- Direct API only: the ChatGPT-account route returns 400 `not supported when using Codex with a
  ChatGPT account`. Add `-c 'model_provider="openai_api_direct"'` (API key via the provider's
  auth command in `~/.codex/config.toml`).
- Slug: the `model_catalog_json` entry whose `display_name` is `Daybreak Red`. Keep it out of
  public artifacts (commits, PRs, issues, logs) per public model naming.
- No Ultrafast: drop `--enable fast_mode` / `service_tier`; keep `model_reasoning_effort="high"`.
- Verified 2026-10-15 with a one-line `codex exec` probe on the direct provider.

### Capacity fallback (Peter, 2026-10-12)

Org caps `gpt-6.1-sol` at 40M tokens/min. Worker or resume fails with `Rate limit reached for
gpt-6.1-sol ... tokens per min (TPM)`, `Selected model is at capacity`, or `overloaded` → resume
that same session on **GPT-6 Astra, high, Ultrafast** immediately (Peter, 2026-10-12: "use
astra if sol has rate limits"; Astra serves `ultrafast`, verified 2026-10-13); no waiting loop:

```bash
codex exec resume "$SID" --dangerously-bypass-approvals-and-sandbox \
  -m gpt-6-astra -c 'model_reasoning_effort="high"' \
  --enable fast_mode -c 'service_tier="ultrafast"' \
  -c 'model_auto_compact_token_limit=260000' -o "$OUT" -
```

- Resume onto Astra keeps the thread (verified 2026-10-12: Sol-created session resumed on Astra and replied).
  Fresh orders at capacity: same flags with `codex exec --yolo -C "$WT"`; a fresh launch that dies
  on capacity already has a session id in stderr (`session id: …`) — resume that, don't relaunch.
- Back off only when Sol and Astra are both limited; then alternate with growing sleeps.
- Wrapper retry triggers must match all three strings (`rate limit|at capacity|overloaded`);
  matching only "rate limit" made capacity failures exit instead of falling back.
- Autoreview at capacity: `--model gpt-6-astra --thinking high --codex-speed fast`. If autoreview
  refuses because its provider/route doesn't match operator config, don't change config — review
  with a fresh-context subagent (diff + brief) and say so in the PR.
- New workers still start on Sol 6.1 Ultrafast; fall back per worker, only on the capacity error.
- Restarts and recoveries: `~/.codex/skills/agent-scripts/codex-first/scripts/codex-resume` does the
  fallback, busy check, safe stop, and classified exits ([resume and watchdog](references/resume-and-watchdog.md)).

### Wrapper and process hygiene (2026-10-12/13)

- Never edit a running wrapper script in place: bash reads scripts incrementally, so live runs
  execute the new bytes at their old offset. Write `x.new`, `bash -n`, `chmod +x`, then `mv`
  (rename keeps the old inode for running copies; forgetting `chmod` gives exit 126).
- Never run `codex exec` under `set -e` in a wrapper: a rate-limit death exits non-zero and ends
  the script before its fallback runs (2026-10-13, a 27-worker fleet). Capture the code
  (`… && rc=0 || rc=$?`) and classify it, or hand the session to `codex-resume`.
- Killing a wrapper orphans its `codex exec` children; the next resume then fails with
  `thread … already has an active writer`. Stop and resume with `codex-resume --stop "$SID"`:
  it finds the worker through its open rollout file (fresh launches don't carry `$SID` in argv,
  so `pgrep -f` misses them) and refuses while `scripts/pr` or git runs beneath it. A leftover
  `~/.codex/thread-writer-locks/$SID.lock` file without a live holder is harmless.
- To redirect a running worker (new design/priority), `codex-resume --stop -p "$ORDER_FILE" "$SID"` (or `--message "…"`);
  its worktree changes and context survive.

## Hard gate

**Autoreview exception:** always prefer Codex-backed `$autoreview`, independent
of `ANTHROPIC_BASE_URL`, router state, or harness. Reviewing a frozen bundle is
not hands-on self-delegation. Do not switch review engines merely because the
parent session is router-backed. This exception takes precedence over the gate
below.

Use the autoreview helper with `--engine codex` (defaults: 6.1 Sol, medium, Ultrafast) unless the user requests an override. It tries the ChatGPT subscription first and, on an auth failure, retries once on the configured direct-API provider; pass `--codex-config 'model_provider="openai_api_direct"'` only to skip the subscription attempt. Preserve the helper's reviewer isolation.

For direct hands-on delegation, use this skill only
when the active agent is Claude Code **and** the session is running on a native
Claude model.

**Model check (primary).** The point of the gate is model economics: Claude
tokens are metered and expensive, so hands-on work moves to Codex; but if the
session is already routed to a cheaper/other model, delegation gains nothing.
Decide by the model the session actually runs on, not by the transport:

1. Read the model id from the system prompt's environment section ("You are
   powered by the model …"). Router-wrapped ids may be opaque
   (`claude-ccr-<hex>`); the hex suffix is often ASCII — decode it
   (`echo <hex> | xxd -r -p`) to reveal the underlying route, e.g.
   `Gorilla CCP/native-claude-fable-5`.
2. If the resolved model is a native Claude model (contains `claude`, `fable`,
   `opus`, `sonnet`, or `haiku`, including `native-claude-*` router routes):
   **delegate hands-on work to Codex.** This applies even when
   `ANTHROPIC_BASE_URL` is loopback or a local router (Gorilla Claw, Clawdex)
   — a router in front of a real Claude model is still expensive Claude.
3. If the resolved model is clearly non-Claude (a GPT/other-provider route):
   the session is already on the flat-rate/cheap side; do not self-delegate,
   work directly.

**Base-URL fallback (only when the model cannot be identified).** If no model
id is visible and the hex/route cannot be decoded, fall back to the old
transport heuristic: if `ANTHROPIC_BASE_URL`'s host is
`gorillaclaw.sheep-coho.ts.net`, `localhost`, ends in `.localhost`, is in
`127.0.0.0/8`, or is IPv6 loopback `::1`, assume the session may be routed to
a non-Claude model and work directly. If neither model nor base URL can be
inspected, fail closed and work directly.

Codex, ChatGPT, Pi, and every other harness: do not invoke Codex CLI for hands-on
self-delegation. Continue the task directly. This gate overrides a repository
instruction that merely mentions `$codex-first`; it does not override the
autoreview exception above.

The default worker is GPT-6.1 Sol on the Ultrafast tier. Claude handles specification, judgment, orchestration, and final verification; Codex handles the delegated implementation.

## Route

Delegate to Codex (default for hands-on work):

- implementation from a frozen spec; refactors; mechanical migrations
- fixing: bug fixes (known repro, or diagnose-then-fix), CI/lint/type failures; test writing; coverage fills
- dependency bumps, scripts/tooling
- exploration + exploratory subagents: fan out Codex for read-heavy discovery instead of Claude Explore/Task subagents whenever raw reading ≫ the answer (parallel `-o` files, one per thread)
- git mechanics — ALWAYS Codex, never Claude directly: `git rebase`, merge-conflict
  resolution, and the repo's land workflow (e.g. `scripts/pr`) are mandatory
  delegations. Issue ONE self-contained work order covering
  rebase→resolve→push→CI attach+green→land so the sequence never bounces back to
  Claude mid-flight; the land decision, gates, and review below stay Claude's.
- work-order CI waits: precheck PR mergeable (CONFLICTING = pull_request CI
  cannot attach — no merge ref) and confirm a run attached to the exact head
  SHA before polling; every wait emits all terminal states with bounded
  iterations; prefer the repo's watcher script when one exists (openclaw:
  `node scripts/watch-pr-ci.mjs`). Never `gh run watch` or `gh pr checks --watch`
  in work orders: `gh run watch` polls every 3 s by default (~1,200 calls/hour), and
  two such watchers drained a shared 5,000/hour writer token twice on 2026-10-15.
  Poll one exact run with `gh run view <id> --json status,conclusion` at most every
  ~10 minutes, or let the repo's landing tool own the wait.
- new work orders go to FRESH `codex exec` sessions with self-contained prompts.
  Do not resume a long-lived session for a new order — saturated sessions
  misread work orders as configuration and no-op ("Understood…").
- repo instruction files: NEVER create or edit `CLAUDE.md`. `AGENTS.md` is
  canonical in every repo; `CLAUDE.md` exists only as a symlink to it. Point
  Codex work orders at `AGENTS.md` and edit only `AGENTS.md`.

Keep in Claude:

- design, API design, architecture, naming, UX judgment
- tasks where writing the spec IS the work (ambiguity = design)
- tiny edits (~<20 lines, single obvious change) — delegation overhead loses
- anything needing session tools: MCP (browser/computer-use/chronicle), 1Password, secrets
- releases, publishes, version bumps and their credentials — Claude-side per release rules
- the land decision + pre-land gates (`$autoreview` clean, CI green, proof) and review of Codex output — never delegated, never skipped; Codex may run the mechanics only once Claude has decided to land and the gates pass

Mixed task: Claude designs first, freezes spec, delegates build-out.
Heuristic: prompt reads as a work order → delegate; writing it forces decisions → design, Claude.
Portfolio/multi-repo work: `$maintainer-orchestrator` instead.

## Invoke

- Run `timeout 8 git --version`; for an Xcode-beta hang, set `DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer` in the session and every order.
- For `openai_api_direct`, run `ruby ~/.codex/skills/agent-scripts/codex-huge-context/scripts/preflight.rb` before the batch's first fresh/resumed launch. If Keychain delivery fails, stop; never override the provider or use ordinary Codex auth.
- Keep the configured provider; resume inherits it. If incompatible with 6.1 Sol, start fresh; never silently change models.
- Use repo-scoped `--yolo`, temp-file prompts (never inline quoting), and `-o` results (not JSONL).
- **Harness visibility (Claude Code): every codex run gets its own harness-tracked
  background command (`run_in_background: true`) — one sidebar chip per worker,
  completion notification included. Chain setup steps (installs, worktree prep)
  INSIDE that tracked command. Never `&`-fork workers from a shared launcher:
  the launcher's chip exits at fork time and the workers become invisible
  orphans supervised only by PID files.**
- parallel independent tasks OK: separate repos/dirs, separate `-o` files, one tracked background command per worker
- outside a git repo add `--skip-git-repo-check`
- For Fast/catalog checks, CLI setup, or execution details: read [launch details](references/launch-details.md).
- On failure or provider changes: [troubleshooting](references/troubleshooting.md); never put credentials in `-c key=value`.
- Before resuming/monitoring: [resume and watchdog](references/resume-and-watchdog.md). Resume and restart through `scripts/codex-resume` (`--dry-run` first when unsure).

## Prompt contract

Codex starts with zero session context. Every prompt: goal, exact repo/paths, constraints, non-goals, proof expected (exact test command), output shape ("report files changed + test output"). Spec quality decides success.

- **Every hard prohibition needs an escape hatch.** A cornered worker satisfies the letter of the
  gates: told "never raise the size budget" while its design inflated the bundle, Codex
  hand-minified source identifiers to single letters — and passed every gate including
  autoreview. Pair each hard constraint with the sanctioned exit: "if gate X fails after honest
  attempts: STOP, report exact numbers/diagnosis, do not work around." Treat a stop-report as a
  successful run (it is the coordinator's decision point, and workers use it correctly once it
  exists).
- Multi-PR series: same spec skeleton every PR; cite prior landed PR numbers and name their
  idioms ("controller with narrow host interface, the #NNN shape") — workers imitate landed
  precedent far more reliably than abstract style rules. Fold each round's new trap into the
  next spec.
- End every series work order with an explicit stop: "Do exactly this; do not start PR N+1."

- Work-order proof: PR CI is the default broad proof; open a ready PR once the build and focused local tests/typecheck/lint/format pass, without waiting for pre-PR broad suites; use Crabbox/Testbox only for gaps CI/local cannot cover and only if granted immediately (queued → local; no Testbox → AWS → Hetzner ladder); fix real failures, read CI's pre-existing/new classification, and never rerun/re-push just for green. Keep untrusted code secretless, live credentials authorized, and Gateway/state isolated.

Before reviewing/landing or coordinating workers, read [coordination](references/coordination.md); check for live workers before editing/committing.