| name | suede-codex-fleet |
| description | Claude-directed parallel OpenAI Codex CLI worker fleet for bulk generation. Use when a job is high-volume, well-specified, and splits into independent worker-sized tasks (content batches, test generation, bulk refactors) and Codex CLI is installed and logged in. Claude decomposes, briefs, spawns codex exec runs in parallel, and review-gates every output. Workers are always codex exec processes billed to the user's OpenAI subscription — never substitute Claude subagent fan-out on any model, and halt rather than fall back if Codex CLI is unavailable. NOT FOR: multi-lane Claude agents coordinating one complex change (use suede-agent-teams); low-volume, judgment-dense copy Claude should write itself (use suede-copy or johnny-suede-write). |
Suede Fable Fleet
The Suede Fable Fleet: a high-end Claude model is the admiral — it decomposes, briefs, and reviews — and parallel OpenAI Codex CLI workers are the fleet. The skill id and command stay suede-codex-fleet on purpose: GitHub search, skill marketplaces, and MCP catalogs match the terms people actually type — Codex CLI orchestration, codex exec, multi-agent worker fleet — not the brand name. Do not rename the folder or frontmatter name to match the brand.
"Fable" in the brand name is not the model claude-fable-5. The workers in this fleet are always OpenAI Codex CLI processes. Never read "Fable Fleet" as license to spawn Claude models.
The workers are Codex processes — never Claude models
This is the economic point of the skill. Codex workers bill to the user's OpenAI/ChatGPT subscription. Claude subagents bill to their Anthropic limit. Someone asking for a codex fleet is deliberately routing volume off the Anthropic meter — satisfying that request with Claude models inverts the cost model and spends the exact budget they were protecting.
codex exec is therefore the only way a worker runs here. Never substitute Agent, Task, Workflow, subagent fan-out, or any other in-house orchestration for a worker — not with fable, not with opus, not with any model, not "just for this one batch". Claude's role is admiral only: decompose, brief, review, assemble. If you are about to spawn something that is not a codex exec process, you have left this skill — stop and re-read the routing table below.
Preflight failure is a halt, not a fallback. If Codex CLI is missing, not logged in, or not on PATH, say which check failed and ask whether to proceed on Claude models, with a rough estimate of what that fan-out will consume. Never fall back silently.
What getting this wrong costs (measured, 2026-07-27): a Claude-model fleet ran in place of an explicitly requested codex fleet — 3,258 turns, ~1.29 billion tokens, 97% of them cache reads from workers each hauling ~500k tokens of context per turn. About $1,843 of API-equivalent spend, 23% of one weekly allocation, for work that should have cost nothing on that account.
When to use this skill instead of related skills
- suede-codex-fleet (this skill): offload high-volume, well-specified generation to Codex CLI workers; Claude plans, briefs, and reviews
- suede-agent-teams: multi-lane Claude agents coordinating one complex code change with gates and handoffs
- suede-copy / johnny-suede-write: Claude writes the copy itself; right choice when volume is low and judgment density is high
Core principle: Claude tokens buy judgment, Codex tokens buy volume. Clear spec + high volume goes to Codex. Fuzzy spec or expensive-if-wrong stays with Claude. Nothing ships unreviewed.
Preflight (run before first spawn)
-
which codex && codex --version — CLI present (validated against codex-cli 0.138.0).
-
codex login status — must show logged in (your ChatGPT subscription pays for the run).
Checks 1 and 2 are the cost boundary. If either fails, stop and report which one — do not substitute Claude workers to keep the job moving.
-
Workspace has an AGENTS.md at its root. Codex auto-loads it; it carries voice, context, hard bans, and output conventions so briefs stay short. If missing, write it first — that is the highest-leverage file in the system.
-
Workspace has briefs/ and out/ directories (create as needed).
The loop
- Decompose. Split the job into independent worker-sized tasks. Independent means: no worker needs another worker's output.
- Brief. One markdown file per task in
briefs/. Codex never sees the Claude conversation, so each brief is self-contained: job, inputs (file paths), exact deliverable, acceptance criteria it must self-check, and the exact output path in out/.
- Spawn. One
codex exec per brief, in parallel, in the background:
caffeinate -i codex exec -C <workspace> --sandbox workspace-write --skip-git-repo-check \
-o <workspace>/out/<run-name>-final-message.txt \
"Read AGENTS.md at the workspace root, then execute the brief at briefs/<brief>.md exactly. Write the deliverable to the output file the brief names, run the brief's acceptance-criteria self-check, and state pass/fail per criterion in your final message."
-C sets the worker's root; --skip-git-repo-check is required outside git repos.caffeinate -i (macOS) is standard on every spawn: it blocks idle sleep for exactly the worker's lifetime and releases on exit, so the machine stays awake while any worker is alive and sleeps normally once the fleet drains. A slept Mac kills every in-flight worker silently. Lid stays open — closed-lid sleep overrides caffeinate unless the Mac is in clamshell mode (external display + power). On non-macOS hosts, drop the prefix.--sandbox workspace-write only. Never danger-full-access. Workers write files; they do not push, deploy, or touch secrets.- Leave the model default unless explicitly asked to override with
-m.
- Review gate (Claude, mandatory). Read every
out/ file. Check against the brief's acceptance criteria and the AGENTS.md hard bans. Worker self-checks are evidence, not verdicts. If the output fails 0 acceptance criteria but has surface defects (typos, formatting, a wrong label), Claude edits the file directly; do not respawn for a comma.
- Delta, don't regenerate. If the output fails 1-2 acceptance criteria, send a one-line correction:
codex exec resume <session-id> "<delta>" (session id is printed at run start; resume --last is ambiguous with parallel runs). If it fails 3+ criteria or violates an AGENTS.md hard ban, respawn with the delta appended to the brief. Regenerating from scratch wastes the subscription and loses what was right. Correction budget per output: up to three genuinely different fixes — each attempt must change the diagnosis or the strategy, never rerun the last one. Stop early when the same root cause repeats across attempts; report the repeating cause and let the user pick the next move.
- Ship. Claude assembles the reviewed survivors into the final deliverable. Report what was spawned, what passed, what got fixed.
Brief template
# Brief <id> — <task name>
Read `AGENTS.md` in the workspace root first. This brief only adds the task.
## Job
<one paragraph: what and why>
## Inputs
<file paths the worker must read>
## Deliverable
<exact structure, counts, variants, labels>
## Acceptance criteria (self-check before finishing)
<numbered, mechanically checkable: limits, bans, required elements>
## Output
Write to `out/<file>.md`. <structure spec>
Fleet workspaces
Keep a persistent workspace per recurring fleet job (a social-content fleet, a test-generation fleet, a refactor fleet) instead of rebuilding context every run. The workspace root holds the AGENTS.md contract, briefs/, and out/. When a brief produces output that passes review cleanly, keep it — proven briefs are the templates for the next run of the same shape.
Hard boundaries
- Workers are
codex exec processes, always. Never substitute Claude-model fan-out (Agent, Task, Workflow, subagents) for a worker, on any model — the brand name "Fable Fleet" is not a reference to claude-fable-5.
- Never ship worker output without the Claude review gate.
- Workers never run git push, deploys, or credentialed commands; content and code-edit tasks only, inside the sandbox.
- Secrets never go into briefs or AGENTS.md; workers get file paths, not tokens.
- If a worker's output violates evidence boundaries or hard bans, the fix is Claude's edit or a delta run, never "close enough".
Troubleshooting
codex exec refuses to start outside a repo: add --skip-git-repo-check.- Every worker died mid-run with truncated or missing output and no error: the machine slept. Spawn with the
caffeinate -i prefix and keep the lid open (or use clamshell mode).
- Not logged in / usage errors:
codex login status, then run codex login interactively.
- Worker wrote nothing to
out/: read the -o final-message file and the task output log; usually a sandbox denial or a brief pointing at a wrong path.
- Parallel runs are independent processes; spawn each with its own background shell call and collect on completion.
Routing Reference
- Multi-lane Claude agent coordination with gates and handoffs -> suede-agent-teams
- Low-volume, judgment-dense copy -> suede-copy / johnny-suede-write
- Proving the assembled deliverable meets spec -> private Suede Labs companion,
not in this pack:
suede-verify
- Skill authoring or estate-lint questions about this file -> private Suede
Labs companion, not in this pack:
suede-skill-forge
