codex
/codex
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.
- Author
- luckeyfaraday ↗
- Repository
- codex-router ↗
- Licence
- MIT
- Last repository change
- 10.07.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 10.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/run-codex.sh
What it does and when to use it
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.
Original author 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.
How it works
- When to offload (and when not to)
- 1. Preflight (once per session)
- 2. Select the worker model
- 3. Write the brief
- 4. Launch
- 5. While it runs
- 6. Review and verify — you own this
- 7. Follow-ups (resume)
- 8. Parallel offloads
- Failure modes
SKILL.md preview
--- 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 |
Files in this package (2)
- SKILL.md 8 KB
- scripts/run-codex.sh 3 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · luckeyfaraday/codex-router | 100 | MIT |
| davila7/claude-code-templates | 100 | MIT |
| tigercosmos/japanese-podcast-learner | 100 | MIT |
| puck-muling/peer-agent | 100 | MIT |
| ispc/ispc | 100 | BSD-3-Clause |
| dzhng/skills | 100 | MIT |
| majiayu000/spellbook | 100 | MIT |
| onlypfachi/chief | 100 | MIT |
| dzhng/skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version e4c44af72f59 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100delegate-codex
Delegate a self-contained piece of work to a Codex CLI worker (`codex exec`) instead of a Claude subagent, picking the Codex tier by difficulty (luna for what Haiku could do, terra for Sonnet-level work, sol for hard jobs), always on the newest model version available. Use when… - 100use-codex
Delegate independent codebase analysis, adversarial review, debugging, implementation, or patching to OpenAI Codex CLI as an external subagent. Use only when the user explicitly asks to use Codex, requests a Codex review or second opinion, or wants Codex to patch files. Route… - 100codex-cli
Run OpenAI Codex CLI for coding tasks, implementation, reviews, and second-opinion audits with mandatory task-based routing across GPT-5.6-or-newer models. Use when a user asks to run, ask, or use Codex; says "codex prompt"; wants a Codex code/logic/plan audit; or wants Claude… - 90collaborate-with-gpt-6
Use when you work with an OpenAI GPT-6 model (GPT-6 Astra, GPT-6.1 Sol, GPT-6 Luna) as a worker or reviewer: understanding its decision habits, choosing the member, briefing it and checking what it returns. Applies through any harness; to run it through Codex CLI, also load `codex`. - 100codex-exec
Delegate checkable execution work to OpenAI Codex through `codex exec` (gpt-6.1-sol, gpt-6-astra) to save Claude usage, or get a review or an adversary pass from another model family. Use whenever a task has a precise spec and a command that proves it done — mechanical… - 90codex-delegate
Orchestrate an implementation task where Claude plans and coordinates while OpenAI Codex performs the actual code edits; plans are cross-reviewed with Codex at its highest reasoning effort before implementation. Use when the user asks to "use codex", "use gpt", "use gpt-5.5",…