Codex

Codex Offload — route heavy work to GPT-5.6

You are the orchestrator and reviewer. Codex is the background worker. Select its model for the task, write a precise brief, launch Codex non-interactively, keep working or wait, then review and verify what it produced. You own final quality — never present Codex's output to the user unreviewed.

When to offload (and when not to)

Offload when the task is heavy but well-specified: large refactors or renames across many files, bulk migrations (API, framework, syntax), generating boilerplate-heavy features from a clear spec, fixing a long list of similar test failures or lint errors, or any task the user explicitly asks to send to Codex or a GPT worker.

Keep it yourself when the task is small (faster to just do it), requires conversation context or user judgment mid-flight, is design/architecture work, or touches secrets and credentials.

1. Preflight (once per session)

codex login status
codex --version

• codex not found → tell the user: npm install -g @openai/codex
• Not logged in → tell the user to run ! codex login (interactive; you cannot do it for them)
• GPT-5.6 requires Codex CLI 0.144.0 or newer. If it is older, tell the user to update Codex before routing to GPT-5.6.

2. Select the worker model

Honor an explicit model request from the user. Otherwise, honor CODEX_ROUTER_MODEL when it is set; it is the user's configured default. If neither chooses a model, route as follows:

Model ID	Use for	Typical effort
gpt-5.6-sol	Hard, ambiguous-but-implementable, cross-cutting, or long-horizon coding work where quality is worth additional time and cost	high or xhigh; use max only when the account supports it
gpt-5.6-terra	The default: well-specified refactors, migrations, and substantial everyday implementation work	high
gpt-5.6-luna	Tightly bounded, repetitive, high-throughput work where latency and cost matter more than frontier reasoning	medium or high

Use the exact IDs above with -m. Codex may expose other models to a particular account; pass an explicit user-requested model through unchanged rather than maintaining an allowlist. Route only to Sol, Terra, and Luna for the GPT-5.6 family—do not invent a gpt-5.6 or sol-pro ID.

Availability varies by plan and workspace. If a model is unavailable and the user did not choose it explicitly, retry once with gpt-5.6-terra and report the fallback. If the user chose it, report the availability error and ask whether they want a different model. Do not retry a run that may have modified the workspace without reviewing it first.

3. Write the brief

Codex starts cold — it sees none of your conversation. The brief must be self-contained. Write it to a temp file (multi-line, no shell-quoting pain) using this shape:

# Task
<one-paragraph goal, stated as an outcome>

# Context
- Repo root: <path>. Key files/dirs: <paths with one-line roles>
- Relevant conventions: <build tool, test command, style rules that matter>

# Requirements
- <numbered, testable requirements>

# Definition of done
- <e.g. `npm test` passes; `grep -r oldApi src/` returns nothing>

# Out of scope
- Do NOT commit, push, or create branches.
- Do NOT touch: <paths>
- <anything else it must leave alone>

Rules: include concrete file paths (Codex can read them itself — point, don't paste whole files); state the verification command; never include secrets, tokens, or .env contents.

4. Launch

Use the wrapper script (in scripts/ next to this SKILL.md). When selecting a model for this run, pass it with -m; when honoring CODEX_ROUTER_MODEL, omit -m. Run it in the background (run_in_background: true) so you can keep working:

<skill-dir>/scripts/run-codex.sh -C /path/to/repo -m gpt-5.6-terra -l short-label - < /path/to/brief.md

Useful flags (defaults are sane — only override with a reason):

Flag	Default	Notes
-C <dir>	cwd	Codex's working root (its writes are sandboxed to it)
-m <model>	gpt-5.6-terra	one-run model selection; $CODEX_ROUTER_MODEL sets the default; accepts any Codex model available to the account
-e <effort>	high	reasoning effort; use an effort supported by the selected model (low/medium/high/xhigh, and max for supported Sol runs)
-s <sandbox>	workspace-write	read-only for analysis-only tasks
--network	off	let the sandbox reach the network (installs, package fetches)
-l <label>	run	names the run directory
--resume <id|last>	—	continue a previous session (see step 7)

The script prints a RUN_DIR containing prompt.md, events.jsonl (live progress), last_message.txt (Codex's final report), and session_id (for resume).

Sandbox escalation: danger-full-access only if the task genuinely needs it AND the user explicitly approves — never by default.

5. While it runs

You'll be notified when the background task exits. Meanwhile, do other useful work. To check progress without interrupting: tail -5 "$RUN_DIR/events.jsonl". Don't poll in a tight loop. If a run seems stuck well beyond a reasonable time for the task, tail the events, then kill the task and either retry with a tighter brief or take over yourself.

6. Review and verify — you own this

When the run exits:

1. Read last_message.txt — Codex's own claim of what it did.
2. Inspect reality, not the claim: git -C <repo> diff --stat, then read the diff for the load-bearing files.
3. Run the definition-of-done checks yourself (tests, grep, build).
4. Small gaps → fix them yourself. Wrong direction or big misses → resume with a corrective follow-up (step 7) or revert and take over.
5. Report to the user: selected model, what was offloaded, what came back, what you verified, and what you fixed.

7. Follow-ups (resume)

Codex sessions are resumable with full memory of the prior run:

<skill-dir>/scripts/run-codex.sh -C /path/to/repo --resume "$(cat "$RUN_DIR/session_id")" -l fixup - <<'EOF'
The tests in tests/api_test.py still fail: <paste failure>. Fix them; everything else was correct.
EOF

--resume last continues the most recent session.

8. Parallel offloads

For independent subtasks, launch multiple runs — but give each its own checkout (git worktree add) so sandboxed writes never collide. Never point two concurrent runs at the same working tree.

Failure modes

Symptom	Fix
codex: command not found	User installs: npm install -g @openai/codex
Not logged in / 401	User runs ! codex login
GPT-5.6 is unavailable / model not found	Verify Codex is at least 0.144.0 and account/workspace access; use Terra as the automatic fallback only when the user did not select the model
Codex reports it couldn't write/run something	Sandbox denial — check if it needed --network, or narrow the task
Empty last_message.txt, nonzero exit	Read stderr.log in the run dir
Result ignores constraints	Brief was ambiguous — resume with explicit corrections, don't relaunch cold