# Subagent Launcher > 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. - Skill: `peteromallet/subagent-launcher` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add peteromallet/subagent-launcher` - Raw SKILL.md: https://api.skillmd.com/api/skills/peteromallet/subagent-launcher/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: peteromallet (https://skillmd.com/u/peteromallet) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/peteromallet/subagent-launcher --- # 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:** > 1. Launch the omp subagent directly from a normal shell or Bash tool. > 2. If you need a **Codex subagent to orchestrate omp subagents**, run the > outer Codex command with `--sandbox danger-full-access` and seal stdin with > ` > ```bash > timeout 3600 codex exec --sandbox danger-full-access \ > -c model_reasoning_effort=high \ > "$(cat /tmp/brief.md)" ``` > > `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. 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`, **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. 3. **DeepSeek V4 Pro** (`deepseek:deepseek-v4-pro`) — reasoning model. Use 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. 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 ""` — 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). ```bash 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" # Final response → stdout; omp progress ("Working...") → stderr. ``` 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-latest` - `codex: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 key** - `grok` (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 rows - `openrouter: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. - **`--timeout`** (default 1800) — subprocess deadline; omp is terminated after it. 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: ```bash 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" # Or positional brief paths instead of --briefs-dir. # Per-brief models: --model-map="fast:scan-*.md,pro:verdict-*.md" ``` Each brief `.md` yields `.txt` (response), `.meta.json` (status/timing/pid), `.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**: ```bash 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: ```bash codex exec --sandbox read-only "$(cat /tmp/prompt.md)" /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 ]` for PR review; `codex apply` to apply its last diff. - **Always seal stdin with ``.** 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: ```bash 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 ` 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: "" }) ``` 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: ```bash 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: ```bash PYENV_VERSION=3.11.11 megaplan init --project-dir "$PWD" \ --profile all-deepseek-pro-direct --robustness light "" # 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 + 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 ``. **Liveness ≠ correctness.** A subagent can stream for 10 minutes and still answer uselessly — read the response; there's no shortcut. ## Quick reference ```bash # 1. omp agentic (default) — DeepSeek/Kimi/Zhipu GLM via omp 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" # Default: --model="deepseek:deepseek-v4-flash" Very fast: --model=fast Pro (reasoning): --model="deepseek:deepseek-v4-pro" Kimi: --model="kimi:kimi-k2.7-code" GLM: --model="zhipu:glm-5.2" GPT: --model="codex:gpt-5.6-sol:high" (ChatGPT subscription, no API key) Grok: --model=grok # Pure chat: --toolsets="" Fan N≥5: fan.py --briefs-dir=… --output-dir=… --max-workers=5 --task-timeout=1800 # 2. Codex (GPT-5.x) — same omp pathway, ChatGPT subscription, no API key python ~/.claude/skills/subagent-launcher/launch_omp_agent.py \ --model="codex:gpt-5.6-sol:high" --query-file=/tmp/brief.md --project-dir="$PWD" # Raw codex exec (sandboxed writes): timeout 1800 codex exec --sandbox workspace-write "" " ```