subagent-launcher

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:

1. Launch the hermes subagent directly from a normal shell or Bash tool.

2. 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.

1. 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.
2. DeepSeek V4 Flash (deepseek:deepseek-v4-flash) — non-reasoning, fast, cheap. High-volume work that needs more coding-tuned behavior than MiMo.
3. 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".
4. 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"
# Final response → stdout; tool progress/timings → stderr.

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 API
  • kimi: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"
# Or positional brief paths instead of --briefs-dir.
# Per-brief models: --model-map="fast:scan-*.md,pro:verdict-*.md"

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>"
# Kimi: --profile all-open

--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

# 1. Hermes agentic (default) — DeepSeek/Kimi/Zhipu GLM with tools
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"
# Very fast: --model=fast   Flash: --model="deepseek:deepseek-v4-flash"   Kimi: --model="kimi:kimi-k2.7-code"   GLM: --model="zhipu:glm-5.2"
# Pure chat: --toolsets=""    Fan N≥5: fan.py --briefs-dir=… --output-dir=… --max-workers=5 --task-timeout=1800

# 2. Codex — always seal stdin with </dev/null, allow 30 min
timeout 1800 codex exec --sandbox read-only "<prompt>" </dev/null              # analysis
timeout 1800 codex exec --sandbox workspace-write "<prompt>" </dev/null        # implementer
timeout 1800 codex exec --sandbox danger-full-access "<prompt>" </dev/null     # orchestrates hermes subagents (network required)
codex exec review --pr 123

# 3. Claude — explicit Opus selector via Claude CLI
python ~/.claude/skills/subagent-launcher/launch_claude_agent.py \
  --model=opus --query-file=/tmp/prompt.md --project-dir="$PWD"

# Multi-phase: megaplan init --profile all-deepseek-pro-direct --robustness light "<task>"