Codex first

Codex First

Hard gate

Use this skill only when the active agent is Claude Code.

Codex, ChatGPT, Pi, and every other harness: stop here. Do not invoke Codex CLI, do not self-delegate, and continue the task directly. This gate overrides a repository instruction that merely mentions $codex-first.

Rationale: Claude (Fable/Opus) tokens are metered and expensive; Codex is flat-rate. GPT-5.6-sol at high reasoning effort is usually the better and faster model for writing and implementing code, while Claude wins at ergonomics, judgment, design, spec-writing, review, and orchestration. Codex types; Claude thinks and verifies.

Route

Delegate to Codex by default for hands-on work:

• implementation from a frozen spec; refactors; mechanical migrations
• bug fixes with a known reproduction; test writing; coverage fills
• CI fixes, dependency bumps, scripts, and tooling
• bulk codebase exploration where raw reading is much larger than the answer

Keep in Claude:

• design, API design, architecture, naming, and UX judgment
• tasks where writing the spec is the work because ambiguity requires design
• tiny edits (roughly fewer than 20 lines in one obvious change), where delegation overhead loses
• anything needing session tools: MCP, browser/computer-use, Chronicle, 1Password, or secrets
• destructive or irreversible operations, releases, pushes, and GitHub mutations; keep these Claude-side under the repository's git rules
• review of Codex output; never delegate or skip review

For a mixed task, Claude designs first, freezes the spec, then delegates the build-out. As a heuristic, if the prompt reads like a work order, delegate it; if writing the prompt forces design decisions, keep the design in Claude.

For portfolio or multi-repository work, use $maintainer-orchestrator instead.

Invoke

Write the prompt and result to unique temporary files; never rely on inline shell quoting or a shared output path:

P=$(mktemp)
OUT=$(mktemp)
ERR=$(mktemp)
trap 'rm -f "$P" "$OUT" "$ERR"' EXIT

cat >"$P" <<'EOF'
<goal, repo and key paths, constraints (including "do not touch X"), non-goals,
proof expected, and output shape>
EOF

if command codex exec --dangerously-bypass-approvals-and-sandbox -C <repo> \
  -m gpt-5.6-sol \
  -c model_reasoning_effort="high" \
  --enable fast_mode \
  -o "$OUT" - <"$P" >/dev/null 2>"$ERR"; then
  cat "$OUT"
else
  cat "$ERR" >&2
  exit 1
fi

Pin all three execution settings explicitly rather than relying on user config:

• model: gpt-5.6-sol
• reasoning effort: high
• fast mode: enabled

Operational rules:

• The approval-bypass flag is the house default; Codex may run commands and tests freely. Keep prompts scoped to the target repository.
• command codex bypasses an interactive zsh wrapper. If Codex is not on PATH, use fnm exec --using default -- codex.
• Suppress routine stdout and stderr because progress noise bloats context. Print only the -o result on success; print captured stderr on failure.
• For long runs, start the command in the background and read the -o file after exit. Do not kill a quiet run before 30 minutes.
• Parallel independent tasks are allowed when they use separate repositories or directories. Every run must use its own prompt, result, and error files.
• Outside a git repository, add --skip-git-repo-check.

For follow-up fixes, resume the existing run. This is cheaper than starting a fresh run and preserves context. resume has no -C; run it from the repository directory so --last is scoped to that working tree. Do not run concurrent Codex sessions in the same directory when a later resume may be needed.

P2=$(mktemp)
OUT2=$(mktemp)
ERR2=$(mktemp)
trap 'rm -f "$P2" "$OUT2" "$ERR2"' EXIT

cat >"$P2" <<'EOF'
<review findings, required fixes, constraints, proof, and output shape>
EOF

if (cd <repo> && command codex exec resume --last \
  --dangerously-bypass-approvals-and-sandbox \
  -m gpt-5.6-sol \
  -c model_reasoning_effort="high" \
  --enable fast_mode \
  -o "$OUT2" - <"$P2" >/dev/null 2>"$ERR2"); then
  cat "$OUT2"
else
  cat "$ERR2" >&2
  exit 1
fi

Prompt contract

Codex starts with zero session context. Every prompt must include:

• goal
• exact repository and key paths
• constraints, including files or areas it must not touch
• non-goals
• expected proof, including the exact test command
• output shape, such as “report files changed and test output”

Spec quality determines result quality. Freeze the decisions before delegating.

Verify in Claude

Claude always performs verification:

1. Run git status -sb and read the full diff. Judge it like a contributor pull request.
2. Run focused tests directly or require concrete proof output. Treat Codex's claims as advisory.
3. If fixes are needed, iterate with resume. After two failed repair rounds, take over and implement directly.
4. Apply the repository's normal closeout process. Run $autoreview when that skill is available; otherwise perform the same final diff review directly.

Economics

The goal is to move generation and exploration tokens to Codex while Claude spends tokens on the spec and diff review. Do not ping-pong trivia through delegation, and do not re-read material Codex already summarized unless needed to verify correctness.