Pi Subagents

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

Install

pi install npm:@maxedapps/pi-subagents

Requires Node 22.19+ and Pi 0.81.1+ (macOS/Linux).

Then start a new Pi session (or /reload).

What you get

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.

Typical flow

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

Start

// 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
})

Status / wait

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 running

Send

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

Stop

subagent_stop({ ids: ["run-…", "run-…"] })

Unknown ids are skipped; others still stop.

How to read results

Every tool result includes roughly:

• state — starting · running · idle · failed · timedout · blocked · stopped
• output — final or partial text
• transcriptPath — full human log
• needsStop — still must be stopped when true
• nextAction — 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.

UI

• Widget under the editor lists open runs.
• /subagents (TUI): ↑↓ select · Enter inspect · r refresh · 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_send to talk to the child.

Timeouts & Esc

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

Custom profiles

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.

Safety

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

License

MIT