Codex

---
name: codex
description: Offload heavy-duty implementation work to OpenAI Codex as a background worker, routing each task to the appropriate available GPT model—especially GPT-5.6 Sol, Terra, or Luna—while Claude stays the orchestrator and reviewer. Use when the user types /codex, asks to delegate/offload/route work to Codex or a GPT model, or when a task is a large mechanical lift—big refactors, bulk migrations, wide test fixes, boilerplate-heavy features—that is better executed by a second agent while you supervise.
---

# 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)

```bash
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:

```markdown
# 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:

```bash
<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:

```bash
<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 |