Audience: an implementing agent (Claude Code or similar) running on any machine. Goal: set up a delegation system for Claude Code where a premium main-loop model (Fable 5 / Opus) acts as orchestrator and routes work to cheaper Claude subagents and to the Codex CLI — expanding the main thread's capability by keeping bulk tool output out of its context window, not by dumbing it down.
Verified against: Claude Code v2.1.205 and Codex CLI v0.142.5 on macOS,
July 2026. Every codex exec flag and config key used here was checked against the
installed binary and the official config reference, and the full system passed an
end-to-end smoke test (Section 5). A full six-lane delegation shakedown (setup →
background Codex audit → Explore → researcher → implementer → verifier) passed
end-to-end on 2026-07-09. Wrapper flags and config keys re-verified against
codex-cli 0.144.5 on 2026-07-17 — compatible, no changes needed. On different
versions, re-verify per Section 3.
Now maintained in a repo: https://github.com/christophermark/agent-toolbox
(tools/delegation-system/) — canonical payloads as reviewable files, an
agent-executable INSTALL.md, a check.sh drift detector, and a runnable
SHAKEDOWN.md live validation. This document remains a self-contained snapshot
for paste-installs.
Read the whole plan before writing anything. All target file contents are given verbatim in Section 4. Follow the idempotency rules in Section 3.
These come from Anthropic's Fable 5 prompting guide, the current Claude Code subagent docs, and post-Fable community playbooks (mid-2026):
- The main thread is the scarce resource. Delegation exists to protect the orchestrator's context window and judgment, not primarily to save money. A session at two-thirds context capacity degrades; every grep dump or test log you keep out of the main conversation is intelligence preserved. Cost savings are a side effect of routing bulk work to Sonnet and Codex.
- The orchestrator keeps: goal understanding, architecture, judgment calls, integration, and final review. Everything mechanical or read-heavy is a candidate for delegation. Ambiguous design work is never delegated — writing the spec is the work.
- Cheapest model that can do the job well — with a quality floor. Sonnet handles everything delegated (retrieval, research synthesis, mechanical implementation, verification); the main model is reserved for orchestration; Codex is an out-of-band lane for large read-heavy jobs and cross-model second opinions. Haiku was considered for the retrieval lane and deliberately rejected: exploration output is navigation ground truth for the orchestrator, and a small model's silent false negatives ("no other call sites exist") poison downstream decisions in exactly the way this system is supposed to prevent. Community measurements report 50–80% cost reduction with no visible quality drop from the orchestrator/executor split alone.
- Fable-era mechanics, not Opus-era mechanics. Fable 5 dispatches parallel subagents reliably and manages long-lived ones. So: prefer background/parallel dispatch with fan-out scaled to the task's structure (a lookup needs one worker; work that genuinely decomposes justifies ten or more — Anthropic's own guidance scales fan-out to complexity rather than fixing a count, and the harness queues any excess), prefer resuming a live subagent over respawning (keeps its context and prompt cache), and use fresh-context verifier subagents instead of self-critique — Anthropic reports these outperform self-review.
- Work orders in, evidence-backed briefs out. Subagents start with zero session context. Every delegation carries: goal, exact paths/symbols, constraints and non-goals, expected proof, and the return shape. Bulk output goes to a scratch directory on disk; only the brief returns to the orchestrator.
- Instructions stay short. Fable-class models follow brief policy statements better than enumerated rulebooks; over-prescriptive skills measurably degrade output. The CLAUDE.md policy below is deliberately compact — do not pad it.
- Guardrails live in structure, not prose. Read-only agents get read-only
tools. Codex runs sandboxed (
read-onlyorworkspace-write), never with approvals bypassed. Commits, pushes, releases, secrets, and destructive ops never leave the main thread.
| Component | File | Model / mode | Role |
|---|---|---|---|
| Delegation policy | ~/.claude/CLAUDE.md (section) |
— | Teaches the orchestrator when and how to route |
| Explore override | ~/.claude/agents/explore.md |
Sonnet, read-only | Keeps built-in exploration off the premium session model (since v2.1.198 Explore inherits it — up to Opus prices). Sonnet over Haiku is deliberate: no silent false negatives in retrieval |
| Researcher | ~/.claude/agents/researcher.md |
Sonnet, read-only + scratch writes, per-project memory | Multi-file synthesis, log/doc digestion, root-cause investigation, state reconstruction |
| Implementer | ~/.claude/agents/implementer.md |
Sonnet, edit+bash, turn-bounded | Mechanical execution of frozen approaches |
| Verifier | ~/.claude/agents/verifier.md |
Sonnet, read+bash, fresh context, persistent memory | Checks finished work against spec; replaces self-review |
| Codex bridge | ~/.claude/skills/delegate-to-codex/ (SKILL.md + wrapper script) |
Codex CLI, sandboxed codex exec |
Large read-heavy jobs, bulk patch drafting, bounded write tasks, cross-model review |
| Scratch convention | .delegate/scratch/ per repo |
— | Disk handoff for bulk material so it never enters the main context |
Division of labor at a glance: Sonnet finds, does, and checks. Codex second-opinions. The main model decides, integrates, and signs off.
This system deliberately stops at report-back subagents plus one external CLI. For work that needs teammates coordinating directly with each other, or fan-out into dozens of independent units, reach for Claude Code's built-in agent teams (https://code.claude.com/docs/en/agent-teams) or Dynamic Workflows (https://code.claude.com/docs/en/workflows) instead — the same orchestrator-keeps-judgment principles apply.
Before writing anything:
claude --version— this plan assumes Claude Code v2.1.198+ (background-by-default subagents, Explore model inheritance,memory/effortfrontmatter). On older versions everything still works; note any gaps to the user instead of failing.command -v codex && codex --version— if the Codex CLI is absent, install Sections 4.1–4.5 anyway and skip 4.6–4.7, telling the user the Codex lane needsnpm i -g @openai/codex(orbrew install --cask codex) pluscodex loginto activate. Do not fail the whole setup.- If Codex is present, check auth with
codex login status(expectLogged in using ChatGPTor an API-key message; if not logged in, tell the user to runcodex login— suggest typing! codex loginin the Claude prompt since it's interactive). - Verify the wrapper's flags against the installed Codex:
codex exec --helpmust list--cd,--sandbox(valuesread-only,workspace-write,danger-full-access),--output-last-message,-c key=value, and--skip-git-repo-check. Config keys used (confirmed in the official config reference as of 0.142.5):approval_policy(valuesuntrusted | on-request | never),model_reasoning_effort(valuesminimal | low | medium | high | xhigh),sandbox_workspace_write.network_access(bool). Adapt the wrapper if the installed version differs, and note what you changed. - Never clobber existing config. For each target file that already exists:
show a diff of what you'd change and ask before overwriting (unless the user has
already told you to proceed autonomously — then upgrade and report the diff
afterward). For
~/.claude/CLAUDE.md, append/replace only the## Delegationsection, preserving everything else. If a previous version of this system is present (e.g. agents namedresearcher/implementerfrom an earlier setup), treat this plan as the newer revision. - Create directories as needed:
~/.claude/agents/,~/.claude/skills/delegate-to-codex/scripts/. If~/.claude/agents/did not exist before the current session, remind the user to restart Claude Code once at the end (the directory watcher only covers directories that existed at session start). - Confirm
CLAUDE_CODE_SUBAGENT_MODELis unset (echo "${CLAUDE_CODE_SUBAGENT_MODEL:-unset}"and checkenvin~/.claude/settings.json) — if set, it overrides all per-agent model routing.
Append (or update in place) exactly this section:
## Delegation
On any nontrivial task, act as an orchestrator: keep your own turns for goal
understanding, architecture, judgment calls, integrating results, and final review.
Push context-heavy and mechanical work into subagents so their tool output never
lands in this conversation. This preserves your context and judgment; cost is the
side benefit.
Routing — cheapest worker that can do the job well:
- `Explore` (Sonnet, read-only): file discovery, symbol tracing, "where/what/how many" lookups.
- `researcher` (Sonnet, read-only): multi-file synthesis, digesting logs/docs/test output, root-cause investigation, reconstructing state after compaction or resume.
- `implementer` (Sonnet): mechanical execution once the approach is frozen — boilerplate, tests, renames, pattern-following refactors, well-scoped slices of a larger plan.
- `verifier` (Sonnet, fresh context): after completing substantial work, have it check the result against the spec instead of reviewing your own work.
- `delegate-to-codex` skill: very large read-heavy investigations, bulk patch drafting, bounded mechanical implementation, and cross-model second opinions on designs or diffs.
- A fork: side tasks that need the full conversation context (a fresh subagent would need too much re-explaining).
How to delegate well:
- Dispatch independent subtasks to subagents in parallel and keep working while they run; intervene if one goes off track or is missing context. Let the task's structure set the fan-out — one worker for a simple lookup, a handful for typical multi-part work, ten or more when it genuinely decomposes — not a fixed count.
- Sequence lanes: dispatch every read/audit lane that must observe the current state before any lane that will change it.
- For follow-ups, resume the existing subagent via SendMessage rather than spawning a fresh one — it keeps its context and cache. SendMessage also re-engages a worker that went idle without reporting.
- Hand every subagent a work order: goal, exact paths/symbols, constraints and non-goals, expected proof, and the return shape. Ask for a short evidence-backed brief; have bulk output written to `.delegate/scratch/` and read back only what you need.
- Prefer the named agents above over unnamed general-purpose spawns (those inherit this session's expensive model).
Never delegate: architectural decisions, ambiguous specs where writing the spec is the real work, secrets/credentials, commits/pushes/releases, destructive operations, or final review and sign-off. Tiny edits aren't worth the round trip — just do them. If you skip delegation on a large task, say why in one line.
This is a personal default; project-level CLAUDE.md files take precedence.Overrides the built-in Explore so exploration runs on Sonnet instead of inheriting
the (premium) session model. Sonnet rather than Haiku is deliberate — see design
principle 3: retrieval results are load-bearing, and the failure mode that hurts is
a silent false negative. Known tradeoff: unlike the built-in, a custom Explore
loads CLAUDE.md and git status at startup (there's no field to skip them), costing
a small amount of context per spawn; acceptable, since the policy file is short.
---
name: Explore
description: Fast read-only codebase exploration — file discovery, code search, symbol and call-site tracing, quick "where/what/how many" questions. Use proactively whenever searching would clutter the main conversation.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a fast, read-only exploration agent. Answer the specific question you were
given and nothing more.
- Never edit files or run commands with side effects; Bash is for read-only
inspection (ls, git log/show/diff, wc, head) only.
- Return exact file paths, symbols, and line references with one line of evidence
each — not narration of your search process.
- If the answer isn't findable, say so and name the most promising place to look
next rather than guessing. Never state that something doesn't exist — state what
you searched for and where, and let the caller judge coverage.
- Report your findings back to the caller as your final message before finishing —
never go idle without delivering the brief.---
name: researcher
description: Use proactively for read-only investigation that needs synthesis — tracing behavior across many files, digesting logs, test output, or documentation, root-cause analysis of a known symptom, and reconstructing project state after compaction or resume. Use whenever the reading involved would consume significant main-session context.
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, Write
model: sonnet
memory: local
---
You are a read-only research agent. Your job is to investigate a specific question
and hand back a short, evidence-backed brief — not to narrate your process or dump
raw material.
Rules:
- Never modify repository files. The only places you may write are
`.delegate/scratch/` (bulk material) and your agent memory directory. Bash is
for read-only inspection only.
- Stay narrow to what was asked; report adjacent discoveries in one line each at most.
- If raw material matters (long logs, large excerpts), write it to
`.delegate/scratch/` in the repo and reference the path instead of pasting it.
- Check your agent memory for relevant prior findings before starting; record
durable, non-obvious discoveries (codebase patterns, gotchas, where things live)
when done.
Return: the answer first, then supporting evidence as `path:line` references with
short quotes, your confidence, and any open questions with what would resolve them.---
name: implementer
description: Use proactively for mechanical implementation once the approach is already decided — boilerplate, straightforward fixes, tests, renames, small pattern-following refactors, and well-scoped slices of a larger plan. Keeps mechanical coding work out of the main conversation.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
maxTurns: 30
---
You are an implementation worker. The caller has already decided the approach; your
job is to execute a narrow, well-specified coding task correctly and efficiently.
Rules:
- Stay inside the given scope. Don't redesign, refactor beyond the ask, or add
abstractions, error handling, or validation for cases that can't happen.
- Make the smallest correct change, matching the conventions of the surrounding code.
- Run the project checks directly relevant to your change (lint/typecheck/focused
tests) when the project defines them.
- If the task turns out to be ambiguous or the frozen approach doesn't survive
contact with the code, stop and report the mismatch instead of guessing.
- Never commit, push, or touch anything outside the workspace.
Return: files changed with a one-line summary each, commands run and their results,
and anything risky or deferred. Do not paste full file contents back.---
name: verifier
description: Use proactively after substantial implementation work (by the main session, a subagent, or Codex) to check the result against its specification with fresh eyes. Fresh-context verification catches what self-review misses.
tools: Read, Grep, Glob, Bash
model: sonnet
memory: user
---
You are a fresh-eyes verifier. You receive a specification (or work order) and a
description of completed work; your job is to independently confirm the work meets
the spec.
Rules:
- Verify against evidence, not claims: read the actual diff/files and run the
relevant checks (tests, lint, build) yourself rather than trusting the report.
- Check the spec item by item: anything missing, anything out of scope, anything
that changes behavior beyond the ask.
- You may run tests and read-only commands; never modify repository files to "fix
things while you're in there" — report instead. Your agent memory directory is
the only place you may write.
- Record generalizable failure patterns in your agent memory — not project
specifics — so future verifications check for them first.
Return: a verdict (pass / pass-with-notes / fail), the spec items checked with
evidence for each, and an exact list of gaps with `path:line` references.---
name: delegate-to-codex
description: Use when delegating work to the Codex CLI from Claude Code — very large read-heavy investigations, bulk patch drafting, bounded mechanical implementation, or a cross-model second opinion on a design or diff. Claude keeps design, review, verification, and all git operations.
---
# Delegate To Codex
Use this skill only from Claude Code. Never ask Codex to delegate back to Claude or
to spawn its own delegation chains.
## When Codex beats a Claude subagent
- The job would burn a very large amount of context on file reading or repetitive
analysis (whole-module audits, sweeping migrations) — Codex runs it fully out of
band with zero token cost to the Claude session.
- You want a genuine second opinion from a different model family on a design,
a diff, or a suspected bug.
- Bulk patch drafting across many files where Claude will review and apply.
Prefer Claude subagents when the task needs session context, MCP tools, or tight
interaction with the orchestrator. Keep in Claude entirely: judgment, architecture,
secrets, commits/pushes/releases, destructive operations, final review.
## Modes
- `research` (default) — read-only sandbox. Investigation, audits, second opinions.
- `patch` — read-only sandbox. Codex returns a unified diff plus verification notes;
Claude reviews it like a pull request, then applies it with its own editing tools
(or `git apply` on a saved patch file).
- `write` — workspace-write sandbox. Bounded implementation with a frozen approach
and narrow file scope only. Requires the target to be a git repository so the diff
is reviewable and reversible. Claude reviews the full diff afterward. Pass
`--network` only if the task genuinely needs outbound network (e.g. installing
a dependency to run tests).
## Work order contract
Codex starts with zero session context. Write the prompt to a file first, including:
goal and success criteria; absolute repo path; relevant files/symbols/logs/commands
already known; constraints and non-goals (including files not to touch); expected
proof (exact test command, or "no commands needed"); and the required output shape.
## Invocation
Always use the wrapper (never hand-write `codex exec`):
```bash
~/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh \
--repo /absolute/path/to/repo \
--mode research|patch|write \
--prompt-file /path/to/work-order.md \
--output /path/to/result.md \
[--model MODEL] [--effort minimal|low|medium|high|xhigh] [--network]The model and reasoning effort default to whatever ~/.codex/config.toml sets;
override with --model/--effort only when the task warrants it. Codex runs take
minutes: run the wrapper as a background Bash task and keep working; read the
output file when it completes.
Never use --yolo, --dangerously-bypass-approvals-and-sandbox, or
danger-full-access.
- Read the output file; verify important claims against the source before relying on them.
- Patches get inspected like a pull request before applying with normal Claude
editing tools. Write-mode diffs get fully reviewed and re-verified (use the
verifiersubagent for substantial changes). - One precise follow-up work order is fine; after two poor rounds, stop delegating and take over.
- Close out as Claude: summarize what changed, cite files, report verification.
### 4.7 `~/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh`
Make it executable (`chmod +x`) after writing:
```bash
#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<'USAGE'
Usage: codex-delegate.sh --repo PATH --prompt-file FILE [--output FILE]
[--mode research|patch|write] [--model MODEL]
[--effort minimal|low|medium|high|xhigh] [--network]
Runs Codex CLI non-interactively and writes its final response to the output file.
research/patch modes run in a read-only sandbox; write mode uses workspace-write
and requires the target to be a git repository. --network enables outbound network
access inside the write sandbox (ignored in other modes). --effort overrides the
Codex config's model_reasoning_effort; when omitted, the config default applies.
On success, prints a provenance line (mode/model/effort) to stderr and the
output file path to stdout.
USAGE
}
repo="" prompt_file="" output_file="" mode="research" model="" effort="" network=0
while [[ $# -gt 0 ]]; do
case "$1" in
--repo) repo="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--prompt-file) prompt_file="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--output) output_file="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--mode) mode="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--model) model="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--effort) effort="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--network) network=1; shift ;;
-h|--help) usage; exit 0 ;;
*) echo "Unknown argument: $1" >&2; usage >&2; exit 2 ;;
esac
done
[[ -n "$repo" && -n "$prompt_file" ]] || { usage >&2; exit 2; }
[[ -d "$repo" ]] || { echo "Repo not found: $repo" >&2; exit 2; }
[[ -f "$prompt_file" ]] || { echo "Prompt file not found: $prompt_file" >&2; exit 2; }
case "$mode" in research|patch|write) ;; *) echo "--mode must be research, patch, or write" >&2; exit 2 ;; esac
case "$effort" in ""|minimal|low|medium|high|xhigh) ;; *) echo "--effort must be minimal, low, medium, high, or xhigh" >&2; exit 2 ;; esac
command -v codex >/dev/null 2>&1 || { echo "codex CLI not found on PATH" >&2; exit 127; }
git_repo=0
git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1 && git_repo=1
if [[ "$mode" == "write" && "$git_repo" -ne 1 ]]; then
echo "write mode requires a git repository (the diff must be reviewable and reversible): $repo" >&2
exit 2
fi
[[ -n "$output_file" ]] || output_file="$(mktemp "${TMPDIR:-/tmp}/codex-delegate.XXXXXX.md")"
combined_prompt="$(mktemp "${TMPDIR:-/tmp}/codex-work-order.XXXXXX.md")"
stderr_file="$(mktemp "${TMPDIR:-/tmp}/codex-delegate-stderr.XXXXXX.log")"
trap 'rm -f "$combined_prompt" "$stderr_file"' EXIT
{
echo "# Delegated Work Order"
echo
cat "$prompt_file"
echo
echo "# Delegation Rules"
echo
echo "- Keep the response concise and evidence-backed; lead with the answer."
echo "- Report commands you ran (or would run) and summarize their results."
case "$mode" in
research)
echo "- You are in a read-only sandbox. Do not edit files."
echo "- Return: answer, paths/symbols with short evidence, confidence, open questions."
;;
patch)
echo "- You are in a read-only sandbox. Do not edit files."
echo "- Return a proposed unified diff for any code changes, then a short"
echo " explanation and verification notes. Do not claim files were changed;"
echo " the caller will review and apply any accepted patch."
;;
write)
echo "- You may edit files inside this workspace, strictly within the requested scope."
echo "- Run focused verification when available."
echo "- Do not run git commit/push or any destructive command."
echo "- Return: files changed, commands run, verification results, risks."
;;
esac
} > "$combined_prompt"
sandbox_mode="read-only"
[[ "$mode" == "write" ]] && sandbox_mode="workspace-write"
args=(
exec
--cd "$repo"
--sandbox "$sandbox_mode"
-c 'approval_policy="never"'
--output-last-message "$output_file"
)
[[ -n "$effort" ]] && args+=(-c "model_reasoning_effort=\"$effort\"")
[[ "$git_repo" -eq 1 ]] || args+=(--skip-git-repo-check)
[[ "$mode" == "write" && "$network" -eq 1 ]] && args+=(-c 'sandbox_workspace_write.network_access=true')
[[ -n "$model" ]] && args+=(--model "$model")
if [[ "${CODEX_DELEGATE_DEBUG:-}" == "1" ]]; then
codex "${args[@]}" - < "$combined_prompt"
else
if ! codex "${args[@]}" - < "$combined_prompt" 2>"$stderr_file"; then
echo "Codex delegation failed. Stderr (first 120 lines):" >&2
sed -n '1,120p' "$stderr_file" >&2
exit 1
fi
fi
if [[ -z "$model" ]]; then
model="$(sed -n 's/^model[[:space:]]*=[[:space:]]*"\(.*\)"/\1/p' "$HOME/.codex/config.toml" 2>/dev/null | head -1)"
model="${model:-unknown} (config default)"
fi
if [[ -z "$effort" ]]; then
effort="$(sed -n 's/^model_reasoning_effort[[:space:]]*=[[:space:]]*"\(.*\)"/\1/p' "$HOME/.codex/config.toml" 2>/dev/null | head -1)"
effort="${effort:-unknown} (config default)"
fi
echo "codex-delegate: mode=$mode model=$model effort=$effort" >&2
echo "$output_file"
Design notes on the wrapper (kept out of the script to keep it lean):
- Non-interactive
codex execcannot answer approval prompts (they fail if no prompt surface exists), soapproval_policy="never"is correct for all modes and safety comes entirely from the sandbox tier. - Codex
--strict-config(added by 0.144.x) was evaluated and deliberately left out of the wrapper: it validates the user's entire~/.codex/config.toml, not just the wrapper's-coverrides, so one unrecognized key in a personal config (e.g. written by a newer Codex desktop app) would break every delegated call. It remains useful as a manual lint when debugging the "-coverride seems ignored" symptom. codex execrefuses to run outside a git repository by default. The wrapper detects this: research/patch add--skip-git-repo-checkfor non-git targets; write mode hard-fails instead, because without git the edits aren't reviewable or reversible.- The work-order file is combined with per-mode delegation rules into one prompt
fed via stdin (
codex exec ... -), and the final message lands in the--outputfile so the orchestrator reads a file instead of scraping a terminal stream. - On success the wrapper emits a one-line provenance record (mode/model/effort) to stderr before printing the output path, so delegation audits can attribute results without digging through the Codex config.
Subagents write bulk material to .delegate/scratch/ inside the repo they're
working in; the directory is created on first use. When working in a git repo, the
orchestrator should ensure .delegate/ is ignored — one line in .gitignore or
.git/info/exclude the first time it's used in a project. Don't do this globally
at install time.
Steps 1–5 are mechanical; 6–7 are live end-to-end tests (they passed as described on the reference machine).
-
ls ~/.claude/agents/→ expectexplore.md,implementer.md,researcher.md,verifier.md. -
Confirm the
## Delegationsection is present in~/.claude/CLAUDE.mdand no pre-existing content was lost. -
test -x ~/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh && echo ok -
bash -n ~/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh && echo "syntax OK", then run the script with no arguments and confirm it prints usage and exits2. -
Confirm
CLAUDE_CODE_SUBAGENT_MODELis unset (Section 3.7). -
Codex smoke test (skip if Codex isn't installed). Build a tiny throwaway repo and delegate a trivial research question through the wrapper:
SMOKE=$(mktemp -d)/smoke-repo && mkdir -p "$SMOKE/src" && cd "$SMOKE" git init -q printf '# Smoke Repo\n' > README.md printf 'export function add(a, b) {\n return a + b;\n}\n' > src/math.js git add -A && git -c user.email=t@t -c user.name=t -c commit.gpgsign=false commit -qm init cat > /tmp/smoke-work-order.md <<'EOF' Goal: Answer two questions about this repository. Success = both answered with exact paths. 1. What files exist at the top level and in src/? 2. What function(s) does src/math.js export, with what signature? Constraints: read-only investigation, no commands needed beyond listing/reading files. Output shape: two numbered answers, one line each. EOF ~/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh \ --repo "$SMOKE" --mode research --effort low \ --prompt-file /tmp/smoke-work-order.md --output /tmp/codex-smoke-result.md \ && cat /tmp/codex-smoke-result.md
Expected: the wrapper exits 0, prints the output path, and the result file contains two numbered answers naming
README.md,src/math.js, andadd(a, b). (Note thecommit.gpgsign=false— machines with global commit signing otherwise fail to create the throwaway commit.) -
Claude subagent smoke test. From the same throwaway repo, run a headless session (headless sessions load
~/.claude/agents/fresh, so this works even before restarting the interactive session):cd "$SMOKE" && claude -p "Use the researcher subagent to state in one sentence what this repository contains, citing one file path."
Expected: a one-sentence answer citing
src/math.jsorREADME.md, proving delegation to the Sonnet-pinned researcher works end to end. -
If
~/.claude/agents/didn't exist before the current interactive session, remind the user to restart Claude Code once so the watcher picks it up.
Verbatim prompts you can use or adapt:
-
Parallel research fan-out:
Research the auth, billing, and API modules in parallel using separate researcher subagents; each returns a brief with
path:lineevidence. Then synthesize the three briefs into one design assessment. -
Plan execution with a long-lived worker: freeze the approach first, then:
Dispatch the implementer subagent with slice 1 of the plan (files, approach, proof command). When it reports, review, then send slice 2 to the same implementer via SendMessage rather than spawning a new one.
-
Close the loop:
Dispatch the verifier subagent with the original work order and the list of changed files. Do not self-certify.
-
Codex as background second brain: at the start of a large job:
Write a work order to
/tmp/wo-audit.mdasking for an audit of module X, then run codex-delegate.sh in research mode as a background task. Continue orchestrating; integrate the Codex brief when it lands. -
Cross-model design review (Codex
researchmode work order):Goal: Second opinion on the design below. Success = a verdict with the top 3 risks, each tied to a concrete file or interface in this repo. Design: [paste the frozen design summary] Relevant files: src/auth/session.ts, src/auth/middleware.ts Non-goals: do not propose a rewrite; critique this design as scoped. Output shape: verdict (sound / sound-with-risks / flawed), then numbered risks with evidence, then open questions.
-
Fork for context-heavy side quests: when a side task needs the whole conversation (e.g. "draft tests for everything we changed so far"), use
/forkor ask for a fork — it shares the prompt cache instead of paying re-explanation.
Anti-patterns to avoid: delegating single-file edits (round-trip overhead exceeds the task), fan-out mismatched to the task (a fleet for a single lookup, or more parallel lanes than you can meaningfully integrate), two subagents writing the same files, letting subagents return raw dumps instead of briefs, and delegating ambiguity.
| Symptom | Cause | Fix |
|---|---|---|
| Wrapper fails instantly with a git error | Target isn't a git repo | research/patch handle this automatically via --skip-git-repo-check; write mode refuses by design |
| Wrapper fails with auth/login error | Codex not logged in | codex login (interactive; in Claude type ! codex login) |
| Subagent not found in interactive session | ~/.claude/agents/ created mid-session |
Restart Claude Code once; thereafter edits hot-reload |
| Explore still runs on an expensive model | Override not loaded, or name mismatch | File must set name: Explore exactly; check /doctor for duplicate-name warnings |
| All subagents run on one model regardless of frontmatter | CLAUDE_CODE_SUBAGENT_MODEL is set |
Unset it in the environment and settings.json env |
| Throwaway-repo commit fails with GPG error | Global commit.gpgsign=true |
Add -c commit.gpgsign=false to the test commit |
-c override seems ignored by Codex |
Key renamed in a newer Codex | Re-verify against codex exec --help and the config reference; adjust wrapper |
| Background subagent goes idle without delivering its brief | Worker finished without messaging the orchestrator | Ping it via SendMessage; agent prompts should end with an explicit report-back line |
- These are personal defaults (
~/.claude/); check project-specific variants into a repo's.claude/agents/when a team should share them. verifieraccumulates cross-project failure patterns in~/.claude/agent-memory/verifier/;researcherkeeps per-project notes in each repo's.claude/agent-memory-local/researcher/(kept out of version control) so codebase-specific "facts" never leak between projects. Prune either if it drifts.- Revisit the Explore override when pricing or built-in behavior changes — its purpose is pinning exploration to the cheapest reliable tier below the premium session model (Sonnet today; Haiku was rejected because silent false negatives in retrieval poison orchestrator decisions).
- If a future Claude Code version warns about unknown frontmatter fields (
memory,effort,maxTurns), consult current docs at https://code.claude.com/docs/en/sub-agents and adapt. - OpenAI ships an official alternative to the wrapper
(openai/codex-plugin-cc, installed
via
/plugin marketplace add openai/codex-plugin-cc). The wrapper here is kept because it enforces the sandbox/mode contract and file-based work orders; the plugin adds interactive review commands if you want both.
- Anthropic, "Prompting Claude Fable 5" — parallel/long-lived subagent guidance, fresh-context verifiers, short-instruction principle: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5
- Claude Code subagent reference (frontmatter fields, Explore model change in v2.1.198, background-by-default, SendMessage resume, forks, memory): https://code.claude.com/docs/en/sub-agents
- Anthropic, "How we built our multi-agent research system" — scale fan-out to query complexity (one agent for simple fact-finding, 2–4 for comparisons, 10+ for complex research): https://www.anthropic.com/engineering/multi-agent-research-system
- Claude Code agent-teams reference — "no hard limit" on teammates; 3–5 is a starting point sized by task density, not a ceiling: https://code.claude.com/docs/en/agent-teams
- Claude Code Dynamic Workflows — the sanctioned high-fan-out mechanism (16 concurrent, 1,000 agents per run) for work that decomposes into dozens-plus independent units: https://code.claude.com/docs/en/workflows
- Codex CLI:
codex exec --help(v0.142.5) and the config reference: https://developers.openai.com/codex/config-reference - Totalum, "Claude Code subagents: the 2026 production playbook" — delegation criteria and anti-patterns (its fixed "3–5 concurrency sweet spot" was dropped from this plan in favor of task-scaled fan-out): https://www.totalum.app/blog/claude-code-subagents-totalum
- Rylaa/fable5-orchestrator — tier routing, disk hand-offs, threshold-gated delegation: https://github.com/Rylaa/fable5-orchestrator
- OpenAI Codex CLI subagents doc: https://developers.openai.com/codex/subagents
- openai/codex-plugin-cc (official Codex-from-Claude-Code plugin): https://github.com/openai/codex-plugin-cc
- Data Science Dojo, "Fable 5 as Orchestrator, Sonnet as Executor": https://datasciencedojo.com/blog/claude-code-fable-5-orchestrator-workflow/