pi-subagents: Pi's delegation layer for focused child agents, parallel reviews, and background work

What pi-subagents actually adds to Pi

pi-subagents is not a standalone agent. It is an extension for the Pi coding agent that gives Pi a delegation tool called subagent. The parent Pi session stays in charge. When you ask for a review, a scout, or a second opinion, Pi starts a child session, gives it a task, and brings the result back. Foreground runs stream into the conversation. Background runs keep working after you get control back. The problem it solves is single-context overload: instead of one model doing everything in one session, you can split work across focused children. The intended user is someone who already uses Pi for real code work and wants a second or third set of model eyes without manually cutting and pasting context between sessions.

The delegation mechanism: parent session, child sessions, and the subagent tool

The core mechanism is simple. Pi is the parent. A subagent is a focused child Pi session with its own job. When you ask for a subagent, Pi starts the child, gives it the task, and brings the result back. The README shows that Pi decides whether to call the subagent tool, which agent to use, and how to compose the work. That means you do not manually invoke a CLI. You write plain language like "Use reviewer to review this diff" and Pi picks the agent. The child session is not a separate process you manage. It is a logical child within Pi's run tree. The README mentions a recursion guard and a cumulative spawn limit, which suggests the design anticipates runaway delegation. The extension also supports session sharing, which the observability doc covers, though the README does not explain the exact sharing mechanism.

Installing and starting: one command, no config required

Installation is a single command: pi install npm:pi-subagents. The README says that is the only required step. You do not need to create agents, write config, or learn slash commands. After installing, you just ask Pi in plain language. The README gives several examples: "Use reviewer to review this diff", "Ask oracle for a second opinion on my current plan", "Use scout to understand this code based on our discussion", and "Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity." There are also prompt shortcuts like /parallel-review and /review-loop, and a /council command for model-based advisors. For checking setup, there is /subagents-doctor. The extension does not start an automatic reviewer in the background. If you want every implementation reviewed, you have to say so in your prompt or project instructions.

The six builtin agents and when to use each

The package ships with six agents. scout is for fast local codebase recon: relevant files, entry points, data flow, risks. researcher does web and docs research with sources and a concise brief. worker handles implementation, edits files, validates, and escalates unapproved decisions instead of guessing. reviewer does code review and small fixes against the task or plan, tests, edge cases, and simplicity. oracle gives a second opinion before acting and challenges assumptions without editing. delegate is a lightweight general delegate that behaves close to the parent session. The README's rule of thumb: scout before you understand the code, researcher before you trust external facts, worker to implement, reviewer to check, and oracle when the decision itself feels risky. That is a clear division of labour, but it depends on Pi choosing the right agent from your prompt. If Pi misclassifies a request, you get the wrong child.

Orchestration and the 64-spawn ceiling

The README describes a recommended implementation loop: clarify, scout, worker, fresh reviewers, worker. It also mentions council-mode and model-based council-* profile examples that you add in your own agent directory. For bounded orchestration, maxSubagentSpawnsPerRun limits cumulative logical children in one run tree. It defaults to 64 and stays separate from active concurrency and the session-wide cumulative spawn budget. That is a concrete constraint: a single run cannot spawn more than 64 children, which prevents unbounded fan-out. The README does not say how to change this value, only that the configuration doc covers it. That is a gap. If you need more than 64 children in one run, you have to read the configuration doc yourself.

Observability and control: FleetView and the fleet inspector

Running work shows up in the TUI as a persistent FleetView below the editor. /subagents-fleet opens a live inspector where you can browse children, read transcripts, steer a running child, or stop a run. You can also just ask "Show me the current async runs" or "Show the subagent fleet." The README mentions machine-readable run artifacts and lifecycle events, but the details are in the observability doc. This is a real strength: you are not launching children into a void. You can inspect and intervene. The README also mentions a watchdog, an opt-in adversarial change reviewer with scope monitoring and LSP checks. That is optional, so the default behaviour is just delegation without adversarial review.

Limitations and the wrong-tool cases

The biggest limitation is trust in Pi's judgement. The README says Pi decides whether to call the subagent tool, which agent to use, and how to compose the work. That is a black box. If Pi picks the wrong agent or composes the work poorly, you get a wasted run. There is also the 64-spawn cap, which is a hard ceiling for a single run tree. For very large parallel audits, that may be too low, and the README does not explain how to raise it. Another limitation: background runs keep working after control returns, but you have to remember to check them. If you forget, work sits unfinished. The extension is also Pi-specific. It is not a general-purpose agent framework. If you do not use Pi, this is useless. And if you prefer a single-context agent that never splits work, this adds complexity you do not need.

A real alternative: manual context splitting

The alternative is not another extension. It is doing the delegation by hand. You can copy the relevant diff, paste it into a fresh Pi session, ask for a review, and paste the result back. That is the approach pi-subagents automates. The difference is that manual splitting requires you to curate the context, choose the task, and merge the result yourself. pi-subagents hands those decisions to Pi. Manual splitting gives you full control over what the child sees, but it is slow and error-prone when you have many files or need parallel reviews. For a single review of a small diff, manual splitting is simpler and has no install cost. For parallel reviewers on a large change, the extension saves real time. The trade-off is control versus convenience.

Editorial conclusion

Adopt pi-subagents if you use Pi for substantial code work and want focused child sessions for review, research, or implementation without building your own orchestration. Skip it if you never need parallel or background work, or if you prefer a single-context agent. Before relying on it, verify the exact behavior of maxSubagentSpawnsPerRun and the council profiles in your own agent directory, since the README points to docs for the details but does not spell out defaults beyond the 64 cap. The project is MIT licensed and actively released, so the cost of trying it is one install command, but the real cost is learning the orchestration patterns and trusting Pi's model to pick the right agent.

Official sources

1. Official README
2. Project repository
3. Release notes