| 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 omp subagent (file/web/terminal tools, one process or fanned out N-wide); also Codex (GPT-5.5), Claude via the Agent tool, and Grok via omp (same x.ai token as the grok CLI). 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.
Pathways:
| Pathway | Model | Invocation | Tools |
|---|
| omp agentic (default) | DeepSeek V4 (Pro/Flash), Kimi K2.7, Zhipu GLM, … | launch_omp_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 |
| Grok via omp | Grok 4.6 / 4.5 | launch_omp_agent.py --model=grok-4.6 | full omp toolset (Bash, Read, Edit, …) |
Default to the omp agentic pathway, and to DeepSeek Flash within it — different model family, cheap, fast, tool-using. Reach for DeepSeek Pro only when the task needs reasoning judgement; 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. omp 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 omp subagent directly from a normal shell or Bash tool.
-
If you need a Codex subagent to orchestrate omp 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 omp provider
API calls from inside codex exec. Tell Codex explicitly to use
launch_omp_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_omp_agent.py --model="deepseek:deepseek-v4-flash"). Need many at once (≥ ~5 parallel)? Same pathway, fan.py.
- Pure chat opinion, no tools? → §1 with
--toolsets="".
- GPT-5.x (Codex) judgement, no API key? → §1/§2,
--model="codex:gpt-5.6-sol". Sandboxed write-heavy work? codex exec --sandbox workspace-write.
- Same-family judgement but isolated from this thread, with explicit Opus/Sonnet selection? → §3 Claude CLI launcher (the only family not yet on omp — no anthropic creds configured). If the host exposes the Claude Code
Agent tool and model selection is not required, that is also fine.
- Want xAI's model with the full omp toolset, no API key, billed to your grok account? → §1/§4,
--model=grok.
- Jury for a high-stakes call? → fan the same prompt to Codex + omp-DeepSeek + omp-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, the default) — non-reasoning, fast, cheap. The default for most dispatches: implementation, mechanical edits, focused investigation, verification. Escalate to Pro only on evidence that reasoning is needed.
- DeepSeek V4 Pro (
deepseek:deepseek-v4-pro) — reasoning model. Use 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. omp 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 runs as a one-off omp (Oh My Pi) process — omp -p --model <model> "<prompt>" — so the agent gets omp's full toolset (Bash, Read, Edit, Glob, Grep, web search, …). No Arnold/megaplan runtime, no key pool: provider availability follows what omp has configured (~/.omp/agent/models.yml + stored credentials). This is the same migration origin/omp-migration performs for megaplan's workers (hermes SDK → omp RPC).
python ~/.claude/skills/subagent-launcher/launch_omp_agent.py \
--model="deepseek:deepseek-v4-flash" \
--toolsets="file,web" \
--query-file=/tmp/brief.md \
--project-dir="$PWD"
Key flags:
--model (default deepseek:deepseek-v4-flash). Prefix convention (translated to omp selectors):
deepseek:deepseek-v4-flash (default, non-reasoning) / deepseek:deepseek-v4-pro (reasoning) → deepseek/…kimi:kimi-k2.7-code → openrouter/moonshotai/kimi-latest (nearest omp catalog row)zhipu:glm-5.2 / zhipu:glm-4.6 → openrouter/z-ai/glm-latestcodex:gpt-5.6-sol / codex:gpt-5.5 — optional :low|:medium|:high effort suffix (maps to omp --thinking) — ChatGPT-subscription Codex backend via omp's openai-codex provider; no API keygrok (shortcut) → grok/grok-4.6 — the grok CLI-proxy provider in ~/.omp/agent/models.yml (same x.ai token as the grok CLI, no API key)fast / mimo / mimo-fast → openrouter/xiaomi/mimo-v2-flash (very fast MiMo path)flash / pro shortcuts → the two deepseek rowsopenrouter:X, google:X, minimax:X, xai:X → translated to the matching omp provider (xai: → the grok CLI-proxy provider); anything else passes through for omp fuzzy matching
--toolsets (default "file,web"): omp gives the full toolset regardless — file/web/terminal is a superset here (native Read/Edit/Write, web search, Bash). "" = pure chat (--no-tools).--query / --query-file — pass exactly one; use --query-file for anything past a sentence.--max-tokens — informational; omp uses the model's native output ceiling (don't set it).--project-dir — cwd for the omp process.
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
For ≥ ~5 parallel agents or programmatic batches, fan.py runs one launcher subprocess per brief (max-workers concurrent), each an omp run. Same flags, plus a briefs directory and per-task output:
python ~/.claude/skills/subagent-launcher/fan.py \
--briefs-dir=/tmp/briefs --output-dir=/tmp/results \
--max-workers=5 --model="deepseek:deepseek-v4-flash" \
--toolsets="file,web" --task-timeout=1800 --project-dir="$PWD"
Each brief <stem>.md yields <stem>.txt (response), <stem>.meta.json (status/timing/pid), <stem>.pid (killable task group), 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). Bump higher for very heavy briefs (e.g. --task-timeout=3600 for cross-file audits). Each task runs in its own process group; fan_kill.py --hard SIGKILLs the whole tree. Below ~5 parallel, just launch launch_omp_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 launcher forwards omp's stderr, ending with [launch_omp_agent] done in N.Ns; a run stuck in "Working..." with no exit for minutes = wedged (check --timeout). For fan.py, watch .meta.json files appearing under --output-dir.
2. Codex (GPT-5.x) — via omp
The canonical Codex dispatch is the same omp pathway as §1 — ChatGPT-subscription
backend through omp's openai-codex provider, no API key:
python ~/.claude/skills/subagent-launcher/launch_omp_agent.py \
--model="codex:gpt-5.6-sol" \
--query-file=/tmp/brief.md --project-dir="$PWD"
codex:gpt-5.6-sol / codex:gpt-5.5 / codex:gpt-5.4 (also gpt-5.6-luna,
gpt-5.6-terra) — optional :low|:medium|:high|xhigh|max effort suffix maps
to omp --thinking (e.g. codex:gpt-5.6-sol:high). Same ChatGPT subscription
as codex exec; omp resolves the OAuth from its own store.- The launcher is model-agnostic: any omp model works through the same command
(deepseek, grok, kimi, glm, gemini, fireworks, …) — see §1 flags.
The raw codex exec CLI remains the alternative when you specifically need the
sandboxed workspace (--sandbox workspace-write) for write-heavy work:
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)
Claude is the one model family with no omp-native route on this machine yet
(omp's anthropic provider needs ANTHROPIC_OAUTH_TOKEN/ANTHROPIC_API_KEY
configured in omp's store). Until then, dispatch through the Claude CLI
launcher — the same one-off pattern, Claude's own toolset:
python ~/.claude/skills/subagent-launcher/launch_claude_agent.py \
--model=opus --query-file=/tmp/brief.md --project-dir="$PWD"
--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.
4. Grok — same canonical omp dispatch
Grok is dispatched through the exact same omp pathway as §1/§2 — the grok
provider in ~/.omp/agent/models.yml (grok CLI proxy, same x.ai token, no API
key). One invocation, the canonical launcher:
python ~/.claude/skills/subagent-launcher/launch_omp_agent.py \
--model=grok --query-file=/tmp/brief.md --project-dir="$PWD"
grok is a shortcut for grok/grok-4.6; grok-4.5 passes through to omp
fuzzy matching. launch_omp_agent.py is the canonical entry for all models.
Auth: omp's ~/.omp/agent/models.yml defines a grok provider pointing at the
CLI's cli-chat-proxy.grok.com proxy; the bearer token is read from
~/.grok/auth.json and rotated by ~/.omp/agent/grok-token.py (OIDC refresh,
~6 h lifetime, refresh on demand — no TUI spawn). Billing and usage limits are
your grok subscription's.
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 + omp-DeepSeek + omp-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.
- omp / fan.py — stuck in "Working..." with no
[launch_omp_agent] done line for minutes = wedged; --timeout bounds it. For fan.py, watch .meta.json files appearing under --output-dir.
- 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
python ~/.claude/skills/subagent-launcher/launch_omp_agent.py \
--model="deepseek:deepseek-v4-flash" --toolsets="file,web" \
--query-file=/tmp/brief.md --project-dir="$PWD"
python ~/.claude/skills/subagent-launcher/launch_omp_agent.py \
--model="codex:gpt-5.6-sol:high" --query-file=/tmp/brief.md --project-dir="$PWD"
python ~/.claude/skills/subagent-launcher/launch_claude_agent.py \
--model=opus --query-file=/tmp/prompt.md --project-dir="$PWD"
python ~/.claude/skills/subagent-launcher/launch_omp_agent.py \
--model=grok --query-file=/tmp/brief.md --project-dir="$PWD"
