| name | subagents |
| description | Delegate a complex or separable task to a focused subagent running in its own tmux pane, watch it work, exchange messages with it, and collect its report. Use when a task benefits from an isolated context (codebase recon, planning, review, a self-contained implementation/fix) or when you want to run several such tasks in parallel. Requires tmux. Subagents are driven via the `subagents` CLI in this skill directory. |
Subagents
Run focused subagents in a dedicated tmux window and talk to them. Each subagent
is an isolated pi instance in its own pane of a window named subagents.
You hand it a task, watch it, send follow-ups, and collect a report. Members are
told apart by their pane titles (subagent#<id> <role>), not the window name.
This is for handoff with a channel back: unlike a one-shot run, you can
answer a subagent's questions, steer it, or unblock it mid-task.
When to use
- A task deserves its own context window (deep recon, planning, review, a
contained implementation or fix) so it doesn't crowd the main conversation.
- Several independent tasks can run in parallel.
- Pick a role from the available role files (see
subagents roles). Each
role carries its own system prompt, model, and tool allowlist.
Do NOT use a subagent for quick, single-step things you can just do yourself.
Running it
The subagents script sits next to this file in the skill directory. Resolve
its absolute path from this skill's location and call it directly — e.g.
<skill-dir>/subagents run .... The examples below write subagents for
brevity; use the full path to the script in this directory.
Commands
subagents roles
subagents run [-m MODEL] [--effort LEVEL] <role> "<task>"
subagents wait <id> [seconds]
subagents reap
subagents status
subagents tell <id> "<message>"
subagents peek <id> [lines]
subagents ls
subagents stop <id|--all>
Choosing a model
A role may pin a default model (kept where the choice is deliberate, e.g. a
cross-family critic). Otherwise pick per task with -m, sized to complexity:
- trivial / mechanical (list files, simple edits) → a small fast model (e.g. haiku)
- standard work (most recon, implementation, review) → a mid model (e.g. sonnet)
- hard reasoning / careful review / adversarial critique → a top model (e.g. opus, gpt-5.x)
Use provider-qualified ids (e.g. anthropic/claude-sonnet-4-6) to avoid an
ambiguous-model error. --effort sets the thinking level (off..xhigh) for harder tasks.
Push mode vs pull mode
If the subagents-watch extension is loaded in the lead (it watches the state
dir), finished reports are pushed into your conversation automatically and
wake you — you don't need to wait or poll. Just run subagents, keep working,
and reports arrive as they complete. Use tell/peek to respond. (Don't also
wait on a subagent the watcher is handling — both consume the same event.)
Without the extension, use pull mode: subagents wait <id> (block for one),
or subagents reap (drain all newly-finished reports) and subagents status
between your own steps.
Workflow (pull mode)
subagents run <role> "<task>" → note the #id.subagents wait <id> → read the report it wrote (or reap to drain all).- If it asks a question or stalls:
subagents peek <id> to see what's happening,
then subagents tell <id> "<answer or nudge>" and subagents wait <id> again.
- Shut it down when done with
subagents stop <id>, unless you expect to
give it more related work soon (subagents keep their context between tasks, so
reuse one for follow-on work rather than spawning a fresh one).
Run several in parallel by issuing multiple subagents runs, then wait each.
Responsiveness (how often to check)
subagents wait polls every couple seconds and returns as soon as the subagent
finishes OR goes idle — including when it hits a blocker, since the protocol makes
it surface the blocker and stop. A single wait blocks for at most ~2 min, then
returns "still working" so you (or the human) can step in; call it again to keep
waiting, or pass a longer timeout: subagents wait <id> 600.
The lead acts one step at a time, so a subagent only gets an answer when you next
wait/peek. For work you want to stay on top of, run then wait (responsive
within seconds). If you fire several and check only occasionally, expect a blocked
subagent to wait until your next check — subagents are told to work autonomously
and stop only for true blockers, so this mostly costs latency, not throughput.
Handling stalls
A subagent reports back by writing a result file; subagents wait also detects
when one goes idle. If wait says the subagent is idle but wrote no report,
or it times out:
subagents peek <id> to read its current state — it may be asking a question
or waiting for a decision.subagents tell <id> "<answer>" to unblock it, or subagents tell <id> "continue"
to nudge, then subagents wait <id> again.- If it's wedged,
subagents stop <id> and start over.
Notes
- Session-scoped: every command (and the watcher extension) only sees and
acts on subagents in the current tmux session. Subagents in other sessions
are invisible and protected —
stop --all never reaches them.
- Requires tmux. Subagents run with built-in tools only (read, bash, edit, write,
grep, find, ls), so roles that depend on external/MCP tools won't have them.
- A role's declared model is used as-is. In an environment with multiple model
providers, role files should use a provider-qualified model id (e.g.
provider/model-name) to avoid an ambiguous-model error at startup.
- If subagents fail to reach a model, the launch command may need a wrapper to
inject provider auth — set
SUBAGENTS_PI (e.g. in a private shell rc) to that
wrapper plus pi. It defaults to pi.
