Run scout, research, and worker children from a Pi parent session—without blocking the parent on every task.
Install once. The parent agent gets four tools and a small UI. You supervise with status/wait/stop (children do not wake the parent automatically).
pi install npm:@maxedapps/pi-subagentsRequires Node 22.19+ and Pi 0.81.1+ (macOS/Linux).
Then start a new Pi session (or /reload).
| Piece | Purpose |
|---|---|
subagent_start |
Launch one child |
subagent_status |
List, snapshot, or wait until settled |
subagent_send |
Follow up (idle) or steer (running) |
subagent_stop |
Tear down runs when done |
| Below-editor widget | Live open runs |
/subagents |
Inspect readable transcripts (TUI) |
Profiles
| Profile | Best for |
|---|---|
scout |
Codebase questions, read-only inspection |
research |
Repo + web research |
worker |
One bounded implementation in a parent-supplied cwd |
Children use the parent’s model/thinking and normally available tools/skills/extensions. They cannot start their own subagents. You own Git, worktrees, and integration.
1. Prepare cwd (worktree if needed) in the parent
2. subagent_start({ profile, task, cwd }) # async default
3. subagent_status({ ids, wait: true }) # join when needed
4. Inspect output / optional subagent_send
5. subagent_stop({ ids }) # always
// background (default)
subagent_start({
profile: "scout",
task: "Where is auth middleware registered?",
cwd: "/path/to/repo",
})
// block until this run settles (still must stop afterward)
subagent_start({
profile: "worker",
task: "Add validation to the signup form",
cwd: "/path/to/worktree",
wait: true,
executionTimeoutMs: 600000, // optional generation deadline
})subagent_status({}) // all open runs
subagent_status({ ids: ["run-…"] }) // snapshot
subagent_status({ ids: ["run-a", "run-b"], wait: true })
subagent_status({ ids: ["run-…"], wait: true, waitTimeoutMs: 5000 })
// waitTimeoutMs → may return waitTimedOut: true; children keep runningsubagent_send({ id, message: "Also check the tests" }) // idle → next generation
subagent_send({ id, message: "Answer now", behavior: "steer" }) // running
subagent_send({ id, message: "…", behavior: "follow-up" }) // running queuesubagent_stop({ ids: ["run-…", "run-…"] })Unknown ids are skipped; others still stop.
Every tool result includes roughly:
state—starting·running·idle·failed·timedout·blocked·stoppedoutput— final or partial texttranscriptPath— full human logneedsStop— still must be stopped when truenextAction— what to do next (wait,send,inspect/retry,stop, …)
| State | Do this |
|---|---|
running / starting |
Wait or status-wait |
idle |
Read handoff; optional send; then stop |
failed / timedout / blocked |
Read error/output; stop |
stopped |
Done for that run |
Rule: never finish a workflow with open runs—subagent_stop everything you started.
- Widget under the editor lists open runs.
/subagents(TUI): ↑↓ select · Enter inspect ·rrefresh · Esc close.- Inside Herdr, Enter can open a live transcript tail pane; elsewhere you get a Pi detail overlay. Viewers are read-only—use
subagent_sendto talk to the child.
| Control | Effect |
|---|---|
executionTimeoutMs |
Child generation deadline → timedout |
waitTimeoutMs |
Your wait only; does not stop children |
| Esc during a blocking tool | Stops running runs in that wait; idle runs stay |
| Parent Esc | Stops running children; idle stays |
| Quit / reload / new session | Stops all open children |
Add Markdown under:
~/.pi/agent/subagents/agents/*.md
---
name: my-reviewer
description: Focused PR review
---
Your system prompt…Same name replaces a bundled profile. Only name, description, and the body are supported.
- Children inherit approved parent capabilities (including project trust). Scope the task and cwd tightly.
- Treat child output as evidence—verify in the parent before merging or shipping.
- Parent owns every Git/worktree operation; children should not manage VCS.
MIT