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

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 c