| name | subagent-launcher |
| description | Launch an external model as a subagent for a second opinion, adversarial review, or delegated work. Default pathway is an agentic DeepSeek / Kimi / Zhipu GLM hermes subagent (file/web/terminal tools, one process or fanned out N-wide); also Codex (GPT-5.5) and Claude via the Agent tool. Use for independent root-cause analysis, cross-checking your reasoning, judge/jury panels, or handing implementation to a different model. |
Subagent launcher (multi-model)
Dispatch work to a model other than the one driving the conversation. Two payoffs: independence — a different model's judgement, not a copy of your own — and context hygiene — the subagent's tool calls and reasoning stay in its context; only the conclusion returns to you.
Three pathways:
| Pathway | Model | Invocation | Tools |
|---|
| Hermes agentic (default) | DeepSeek V4 (Pro/Flash), Kimi K2.7, Zhipu GLM, … | launch_hermes_agent.py — or fan.py to run N in one process | file, web, optional terminal |
| Codex | GPT-5.5 | codex exec (CLI) | sandboxed workspace |
| Claude | Claude (Opus/Sonnet/Haiku) | launch_claude_agent.py --model=opus or Claude Code Agent tool | Claude Code tools |
Default to the hermes agentic pathway, and to DeepSeek within it — different model family, cheap, tool-using. Reach for Codex or Claude only when you specifically want their strengths.
⚠️ Network sandbox warning for Codex subagents
codex exec runs its subprocess with CODEX_SANDBOX_NETWORK_DISABLED=1. Hermes agents (DeepSeek/Kimi/MiMo/GLM/OpenRouter) need outbound network to reach their provider APIs, so launching them from inside a codex exec subagent will fail. The launcher itself is fine; it fails only because the parent process has no network.
Workarounds:
-
Launch the hermes subagent directly from a normal shell or Bash tool.
-
If you need a Codex subagent to orchestrate hermes subagents, run the
outer Codex command with --sandbox danger-full-access and seal stdin with
</dev/null, for example:
timeout 3600 codex exec --sandbox danger-full-access \
-c model_reasoning_effort=high \
"$(cat /tmp/brief.md)" </dev/null
read-only and workspace-write both disable outbound network for the
Codex subprocess; only danger-full-access allows nested Hermes provider
API calls from inside codex exec. Tell Codex explicitly to use
launch_hermes_agent.py or fan.py, and to spend its own context budget
by delegating broad searches, file mapping, and independent reviews to
DeepSeek/Kimi subagents wherever practical.
This network restriction does not affect Codex or Claude subagents.
Picking a pathway
- Default — an independent DeepSeek/Kimi subagent that reads the repo itself? → §1 (
launch_hermes_agent.py --toolsets="file,web"). Need many at once (≥ ~5 parallel)? Same pathway, fan.py.
- Pure chat opinion, no tools? → §1 with
--toolsets="".
- Most-different-from-Claude judgement, or write-heavy implementation in a sandbox? → §2 Codex.
- Same-family judgement but isolated from this thread, with explicit Opus/Sonnet selection? → §3 Claude CLI launcher. If the host exposes the Claude Code
Agent tool and model selection is not required, that is also fine.
- Jury for a high-stakes call? → fan the same prompt to Codex + hermes-DeepSeek + hermes-Kimi in parallel; divergence is the signal.
- Bigger than ~a day or two of work? → it's a deliverable, not a dispatch: run a
megaplan (itself launched as a subagent) and size it with the megaplan-decision skill. Past ~2 weeks → an epic.
- Already have the answer? → don't dispatch. Subagents aren't free.
Use the cheapest subagent that can do the job
Independence is the why; cost is the which. Default to the cheapest model that can plausibly succeed; escalate only on evidence.
- MiMo V2.5 Pro Ultraspeed (
fast, alias for mimo:mimo-v2.5-pro-ultraspeed) — very fast. High-volume, low-judgement work: scan files, extract facts, short first-pass research.
- DeepSeek V4 Flash (
deepseek:deepseek-v4-flash) — non-reasoning, fast, cheap. High-volume work that needs more coding-tuned behavior than MiMo.
- DeepSeek V4 Pro (
deepseek:deepseek-v4-pro, the default) — reasoning model. When the task needs judgement: root-cause analysis, "is this sound", "should this merge".
- GPT-5.5 (Codex) or Claude — only for real complexity: subtle multi-step reasoning, write-heavy implementation, the strongest adversarial review.
Two rules: start low, escalate on evidence (don't reach for the frontier model "to be safe"); and prepare the context so a cheap model can win — most "cheap model failed" cases are under-specified prompts. A moment spent scoping the task is cheaper than burning a Claude subagent on something Flash could do.
Beware the asymmetry: reasoning models handed mechanical briefs refactor (because that's what reasoning does); non-reasoning models handed architectural briefs literally execute fragments without understanding the intent. Match brief shape to model mode, not just model to task.
1. Hermes agentic (DeepSeek / Kimi / Zhipu GLM) — the default
A real tool-using agent in a non-Claude model's voice, far lighter than a megaplan run. It wraps megaplan's AIAgent primitive as a standalone CLI: the agent reads files, searches the codebase, fetches URLs, and (with terminal) runs commands — single-turn, no plan state or critique loop. For a pure-chat opinion with no repo access, run the same command with --toolsets="".
The launcher discovers the active runtime itself. It first tries an installed legacy megaplan.agent distribution, then falls back to the current Arnold checkout (~/Documents/Arnold by default, or ARNOLD_PATH=/path/to/Arnold). Do not add an arnold_pipelines.megaplan.agent compatibility package to fix import failures; the real Hermes runtime lives under arnold.pipelines.megaplan.agent in the Arnold checkout.
PYENV_VERSION=3.11.11 python ~/.claude/skills/subagent-launcher/launch_hermes_agent.py \
--toolsets="file,web" \
--query-file=/tmp/brief.md \
--max-tokens=65536 \
--project-dir="$PWD"
Key flags:
--model (default deepseek:deepseek-v4-pro). Prefix convention from the megaplan key pool:
fast, mimo, mimo-fast → mimo:mimo-v2.5-pro-ultraspeed (very fast MiMo path; requires MIMO_API_KEY)deepseek:deepseek-v4-pro (default) / deepseek:deepseek-v4-flash (faster, non-reasoning) → DeepSeek APIkimi:kimi-k2.7-code → Kimi coding API (requires KIMI_API_KEY or MOONSHOT_API_KEY)zhipu:glm-5.2 / zhipu:glm-4.6 → Zhipu GLM API (requires ZHIPU_API_KEY)google:gemini-…, minimax:MiniMax-M2, … — see megaplan/runtime/key_pool.py:resolve_model
--toolsets (default "file,web"): file (read_file/write_file/patch/search_files), web (fetch_url), terminal (shell — no sandbox, runs as you; never for untrusted prompts). "" = pure chat.- Note: in the standalone
launch_hermes_agent.py entrypoint, the file toolset is only available when terminal is also enabled, because file operations are routed through the terminal environment. If the agent emits tool-call markup but does not actually read files (or claims it has no filesystem access), pass --toolsets="file,web,terminal".
--query / --query-file — pass exactly one; use --query-file for anything past a sentence.--max-tokens (default 65536 — model output ceiling for DeepSeek V4). In normal use, do not pass this flag. The launcher already defaults to the model's ceiling, so adding it yourself just creates copy-paste noise and makes it easy to accidentally inflate the cap for no benefit. These are reasoning models; reasoning tokens are billed and counted against max_tokens, so a brief that fires 20+ tool calls can burn the entire budget on reasoning before emitting a single output token — the result is an empty answer (finish_reason: length) with the tool history visible in stderr. The built-in ceiling protects against that silent failure. Only pass --max-tokens when you specifically want a shorter cap because you have already scoped the brief to ≤5 tool calls and want to bound cost/output length. Other ceilings: Kimi K2.7 ~32768, Zhipu GLM-5.2 / GLM-4.6 ~32768, DeepSeek Flash 8192 (non-reasoning, doesn't burn budget on thinking so 8K is fine).--project-dir — chdir so the file tool resolves relative paths as you expect.- Runtime discovery — set
ARNOLD_PATH=/path/to/Arnold only for nonstandard checkouts. Normal shells should not need manual PYTHONPATH.
--context-budget-tokens — raise the auto-compaction floor when a broad file audit on a long-context model compacts too early, e.g. --context-budget-tokens=100000.
Output is freeform text — if you want JSON, ask for it in the prompt and parse defensively; for an enforced schema, use megaplan, not this pathway.
Fan out N at once — fan.py
launch_hermes_agent.py is one subprocess per call; each re-imports the Arnold/Hermes runtime. For ≥ ~5 parallel agents or programmatic batches, fan.py runs N AIAgents in one process (imports once, ~5–15× less RAM). Same flags, plus a briefs directory and per-task output:
PYENV_VERSION=3.11.11 python ~/.claude/skills/subagent-launcher/fan.py \
--briefs-dir=/tmp/briefs --output-dir=/tmp/results \
--max-workers=5 --model="deepseek:deepseek-v4-pro" \
--toolsets="file,web" --max-tokens=65536 --task-timeout=1800 --project-dir="$PWD"
Each brief <stem>.md yields <stem>.txt (response), <stem>.meta.json (status/timing/tool_calls), and an aggregate _report.json. Kill a running fan from another shell: fan_kill.py --output-dir=… [--hard]. Default --task-timeout=1800 (30 min — forensic work with ≥10 tool calls routinely exceeds 10 min; the old 600s default would silently SIGKILL agents mid-investigation). Bump higher for very heavy briefs (e.g. --task-timeout=3600 for cross-file audits). Add --isolation=processes if you need to SIGKILL one task without touching the rest. Below ~5 parallel, just launch launch_hermes_agent.py N times in parallel Bash calls — simpler.
Use megaplan instead when you need
multi-phase orchestration (plan → critique → revise → execute → gate → review), schema-enforced output, persistent plan state / approval gates, or the megaplan sandbox. See Multi-phase delegation below.
Liveness
The script logs [tool] / [done] to stderr every 1–5 s while alive and ends with [launch_hermes_agent] done in N.Ns. No new tool lines for minutes = wedged. For fan.py, watch .meta.json files appearing under --output-dir.
2. Codex (GPT-5.5)
codex exec from Bash (the /codex:* plugin wraps the same call).
codex exec --sandbox read-only "$(cat /tmp/prompt.md)" </dev/null > /tmp/out.txt 2>&1
--sandbox read-only | workspace-write | danger-full-access — analysis / let it edit files / full shell.-c model_reasoning_effort=low|medium|high — medium default.codex exec review [--pr <n>] for PR review; codex apply to apply its last diff.- Always seal stdin with
</dev/null. Otherwise codex exec blocks forever at Reading additional input from stdin... (0% CPU, no error) even when the prompt is in argv. That banner prints on healthy runs too — the wedge signal is the output file not growing. Wrap long runs in timeout 1800 (30 min — review and write-heavy briefs routinely run 15+ min; 600s is too tight).
3. Claude (Opus/Sonnet/Haiku)
Use the Claude CLI launcher when you need an explicit model selector from any
host, including Codex sessions where the platform spawn_agent tool does not
expose a model field:
python ~/.claude/skills/subagent-launcher/launch_claude_agent.py \
--model=opus \
--query-file=/tmp/brief.md \
--project-dir="$PWD" \
--tools="Read,Grep,Glob" \
--timeout=1800
--model accepts Claude Code aliases such as opus / sonnet / haiku or a
full model name such as claude-opus-4-8. The launcher invokes
claude --print --model <model> with --project-dir as the subprocess cwd and
prints the final answer to stdout while diagnostics go to stderr. It leaves
Claude Code's default tool policy alone unless you pass --tools; use
--permission-mode deliberately. It adds --no-session-persistence by default
so one-off subagents do not clutter Claude history; pass --keep-session when
you want resumability.
When you are already inside Claude Code and the Agent tool is available,
you can still dispatch through it — cleanly-scoped, no memory of the outer
conversation, so the prompt must be self-contained. Subagent types:
general-purpose (full tools), Explore (fast read-only search), Plan
(architect, no code), claude-code-guide, code-reviewer.
Agent({ description: "…", subagent_type: "general-purpose",
prompt: "<self-contained brief: working dir, files, what to return, length cap>" })
Prefer Claude over Codex when you want the same family of judgement isolated from this thread (keeping the main context clean), or specifically want Opus judgement. For genuinely different model-family judgement, prefer Codex, DeepSeek, or Kimi.
Multi-phase delegation (when a single-turn agent isn't enough)
When DeepSeek/Kimi need a full plan-execute-review cycle across many files, route through megaplan:
PYENV_VERSION=3.11.11 megaplan init --project-dir "$PWD" \
--profile all-deepseek-pro-direct --robustness light "<task>"
--robustness light is a fast single pass; drop it for the full workflow (default full). The megaplan-decision skill covers the profile / robustness / depth dials.
Writing the prompt (any pathway)
The receiving model has zero context from your conversation. Brief it like a smart colleague who just walked in:
Is your brief a spec or a memo? A spec lists inputs and outputs (do X at line Y, then Z). A memo explains context and asks for judgement. Reasoning models will treat any memo as license to architect — even if the underlying ask was 5 mechanical edits. If the work is mechanical, strip the rationale; the "why" belongs in the commit message, not the brief.
- Working directory and exact file paths (not "the relevant files").
- Goal + why it matters; what you've already ruled out.
- Output shape and a length cap ("ranked list, < 300 words").
- For adversarial / second-opinion work, tell it to take a position and not hedge — otherwise it hedges.
- Anti-pattern: the options menu. "Pick whichever of A/B/C fits" reliably invites a reasoning model to optimize across the options and often produce a fourth one you didn't ask for. One ask, one solution path. Save options menus for genuine judgement calls — and when you do use them, route the work to a non-reasoning model that can't optimize past them.
Don't dispatch what you already know, and don't re-ask what you've answered — add a twist (rank these, find the flaw, argue the other side) or skip it.
Judge / jury for high-stakes calls
Send the same unbiased prompt to several models in parallel (Codex + hermes-DeepSeek + hermes-Kimi, optionally a Claude Agent) and compare — convergence on a subtle call is far stronger than one model's confidence; divergence is signal. Reserve it for risky pre-merge reviews, hard-to-reverse architecture calls, security-sensitive paths. Don't fan out routine work. For a multi-lens sense-check of one proposal (human-user / agent-user / abstraction lenses), give each agent only its own lens and never show one's output to another.
Detecting hangs
Check liveness 30–60 s after launch, not 10 minutes in.
- Codex — see the
</dev/null wedge above; the tell is an output file stuck at the banner size while wall-clock climbs.
- Hermes / fan.py —
--max-tokens too low → empty answer (finish_reason: length); else watch the stderr [tool]/[done] heartbeat.
- Claude Agent / launcher — synchronous, rarely wedges; the common failure is a terse prompt → shallow hedged answer in < 30 s. Cap length and demand a position.
- megaplan — an "stuck" run is usually a gated step awaiting approval;
megaplan status --plan <name>.
Liveness ≠ correctness. A subagent can stream for 10 minutes and still answer uselessly — read the response; there's no shortcut.
Quick reference
PYENV_VERSION=3.11.11 python ~/.claude/skills/subagent-launcher/launch_hermes_agent.py \
--model="deepseek:deepseek-v4-pro" --toolsets="file,web" \
--query-file=/tmp/brief.md --max-tokens=65536 --project-dir="$PWD"
timeout 1800 codex exec --sandbox read-only "<prompt>" </dev/null
timeout 1800 codex exec --sandbox workspace-write "<prompt>" </dev/null
timeout 1800 codex exec --sandbox danger-full-access "<prompt>" </dev/null
codex exec review --pr 123
python ~/.claude/skills/subagent-launcher/launch_claude_agent.py \
--model=opus --query-file=/tmp/prompt.md --project-dir="$PWD"
