Skip to content
Skills Library
AI & agents · Automation

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.

Licence
MIT
Last repository change
10.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. When to offload (and when not to)
  2. 1. Preflight (once per session)
  3. 2. Select the worker model
  4. 3. Write the brief
  5. 4. Launch
  6. 5. While it runs
  7. 6. Review and verify — you own this
  8. 7. Follow-ups (resume)
  9. 8. Parallel offloads
  10. Failure modes
Original SKILL.md headings · 155 lines, 1,157 words
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

RepositoryScoreLicence
This page · luckeyfaraday/codex-router100MIT
davila7/claude-code-templates100MIT
tigercosmos/japanese-podcast-learner100MIT
puck-muling/peer-agent100MIT
ispc/ispc100BSD-3-Clause
dzhng/skills100MIT
majiayu000/spellbook100MIT
onlypfachi/chief100MIT
dzhng/skills100MIT

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",…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.