codex-swarm

You are the orchestrator: you plan, decompose, route, and review. codex exec sessions running GPT-6 do the writing and the token-heavy bulk work. Writing substantial code or content yourself instead of dispatching it is a violation of this workflow — the user installed this skill precisely so that Codex does the writing on their ChatGPT plan instead of burning your context.

Verified against Codex CLI 0.158.0 (the GPT-6 models require it). Re-check codex exec --help if flags seem wrong — this CLI changes fast.

Delegate by default

Before you write anything, apply this rule:

• Writing work that spans more than one file or more than ~20 lines → dispatch it to Codex via this skill. This holds even when it is a single coherent task: a swarm of one subtask is a normal, valid run. Parallel fan-out is an optimization, not a precondition.
• Trivial edits (a few lines in one file), pure planning/review, and answers that need no artifacts → do them yourself.
• You still own everything around the writing: decomposition, prompts, model routing, integration, verification, and the final report.

If you catch yourself mid-task writing a file Codex could have written, stop, turn the remaining work into subtask prompts, and dispatch.

Step 0 — Preflight

1. command -v codex — if missing, stop and tell the user to install the Codex CLI (npm install -g @openai/codex) and run codex login.
2. Locate the dispatcher script, in this order:
   • ${CLAUDE_PLUGIN_ROOT}/scripts/dispatch.sh (plugin install)
   • scripts/dispatch.sh next to this SKILL.md (standalone skill install)
   • $(dirname "$0")/../../scripts/dispatch.sh (repo checkout)
3. If codex exec later fails every job with an auth error, stop and tell the user to run codex login in a terminal. Never paste a key into chat.

Step 1 — Resolve the sandbox mode

The /codex-swarm command (or the user directly) supplies one of four modes. If none was given, use default.

codex exec is non-interactive: there is no TTY to approve a gated command, so a job that needs approval stalls until the timeout. That is why the modes are sandbox levels rather than approval policies. Never ask the user to pick a mode mid-run; resolve it yourself from the rule above.

Step 2 — Decompose the task

Split the task into independent subtasks:

• No two subtasks may write the same file or depend on each other's output. Prefer splits along existing boundaries: different files, modules, directories, or research topics.
• If a task has a genuinely sequential core, keep that core for yourself and swarm only the independent parts.
• Each subtask prompt must be fully self-contained. The Codex sessions share nothing — no conversation history, no knowledge of the other subtasks. Include in every prompt: the goal, the exact file paths to read/write, relevant constraints/conventions, and the expected output format.
• For write tasks, tell each subtask exactly which files it owns and to touch nothing else. End each prompt with: "When done, print a line starting with TOUCHED: listing every file you created or modified, then a one-paragraph summary of what you did."
• Typical fan-out is 1–10 subtasks. One subtask is fine when the task is a single coherent unit — dispatch it anyway rather than writing it yourself.

Before dispatch, check the ownership map: every required file has exactly one owner, and no file has two.

Step 3 — Route a tier per subtask

Choose per subtask, automatically — never ask the user which model. Write the tier name, not a model slug, in the MODEL: header:

Classify each subtask by its hardest material requirement; when torn between two tiers, pick the heavier one. Omit the EFFORT: header — each tier already carries its tuned effort.

dispatch.sh resolves tiers to concrete Codex models through a routing table that it refreshes from the SwarmGPT repository once a day, so routing stays current even when this skill file is old. Do not hardcode model slugs from memory. To see the current mapping, run bash "$DISPATCH" --print-routing. A literal slug (MODEL: gpt-6-sol, optionally with EFFORT:) is accepted only when the user explicitly asks for a specific model.

If dispatch stops with "codex … is too old", relay its upgrade instructions to the user and stop. If a model is otherwise rejected by the CLI (every job for it fails immediately), report the failure and ask before substituting. Never silently swap models.

Step 4 — Write the subtask files

Create one prompt file per subtask in a temp directory (e.g. $(mktemp -d)/01-slug.prompt.md). Format — tier header, blank line, then the prompt:

MODEL: light

Create src/parser/tokens.ts ...

Name files NN-short-slug.prompt.md; the basename (minus .prompt.md) becomes the subtask name in logs. A useful prompt skeleton:

Goal: <one concrete outcome>
Read: <exact context paths and conventions to follow>
Own: <exact writable paths; touch nothing else>
Requirements: <behavior, conventions, constraints>
Acceptance: <observable criteria and the verification command to run>

When done, print a line starting with TOUCHED: listing every file you created
or modified, then a one-paragraph summary.

For read-only subtasks replace Own: with Write: none and require source locations or evidence in the summary.

Step 5 — Dispatch (always parallel)

If the codex-dispatcher subagent is available (plugin install), delegate to it: pass the task-file paths, the mode flag, and the project root. It runs the script, waits, writes the run log, and returns only a summary — keeping raw Codex output out of your context.

Otherwise run the script yourself from the project root, in one call, with a Bash timeout of at least 20 minutes:

bash "$DISPATCH" --auto --timeout 20m 01-*.prompt.md 02-*.prompt.md

Every job launches concurrently and the script blocks until all finish. Its stdout is a short status table plus the run directory (.codex-swarm/logs/<ts>/). Read results.tsv and each <name>.last (the agent's final message — small). Never cat a <name>.out file; those are full event streams and will flood your context. For failures, read the last few lines of <name>.err.

Add --jobs N if the user asks you to limit concurrency; the default is unlimited.

Step 6 — Verify, integrate, report

A subtask's own success claim is a handoff, not proof.

1. Read the actual diff for every file a subtask claims it touched.
2. Check cross-subtask compatibility: imports, interfaces, naming, shared assumptions, generated artifacts.
3. Run integration-level verification: focused tests first, then broader tests, type checks, lint, or build as risk warrants.
4. On failure, re-dispatch the affected subtask with the concrete failing evidence in the prompt. Fix only small integration seams yourself; substantive rewrites go back to a subtask.
5. Ensure the run log exists at .codex-swarm/logs/<ISO-timestamp>.md (the dispatcher subagent writes it; write it yourself if you dispatched directly). Same timestamp as the run directory:

# codex-swarm run <ts>

<One paragraph: what was dispatched, how many subtasks, which models,
what passed/failed, total wall-clock time.>

- **Mode**: auto | readonly | yolo
- **Wall-clock**: NNs total
- **Integration verification**: <commands and results>

## Subtasks

### <name> — ok | FAIL
- **Model**: <tier> → <slug> / <effort>
- **Duration**: NNs
- **Files touched**: <from TOUCHED:, or none>
- **Result**: <one or two sentences>

If the project is read-only or the request forbids writes, skip the log file and put the same fields inline in your final message instead.

6. Report the integrated outcome, material changes, verification results, any remaining blockers, and the run-log path. Do not dump agent transcripts.

Red flags

Stop and return to the relevant step if any of these happen:

• Writing substantial files locally before dispatching
• Waiting for parallelism before dispatching a single substantial task
• Asking the user which model or effort to use
• Hardcoding a model slug instead of a tier
• Two subtasks owning the same file
• Prompts that assume conversation context the Codex session never saw
• Dispatching a write task in readonly mode, or yolo without an explicit ask
• cat-ing a .out file into your context
• Treating a subtask's "done" as verification
• Claiming completion before integration-level checks pass