pi-subagents: Async Subagent Delegation for the Pi Coding Agent

What pi-subagents adds to a Pi session

Pi is the parent session. A subagent is a focused child Pi session with its own job. The extension's contribution is a delegation tool: when you ask for a subagent, Pi starts the child, hands it the task, and brings the result back into the parent conversation.

The audience is people already working inside Pi who keep hitting the same wall: one context window has to hold the plan, the diff, the tests, and the review at once. Delegation splits that. The README lists the intended uses as code review, scouting, implementation, parallel audits, saved workflows, and background jobs, and describes the motivation as "a second or third set of model eyes." That is a fair summary of the design: the value is a separate session with its own context, not a smarter model.

One thing the README states plainly, and it matters for expectations: installing the extension does not start an automatic reviewer in the background. It gives Pi a tool. If you want every implementation reviewed, you have to say so in your prompt or project instructions. Teams that install this expecting a gate will be disappointed.

The parent and child session model, and where runs surface

The architecture is two-tier. The parent session holds the conversation and the delegation tool. Each child is a Pi session with a task. Foreground runs stream progress into the conversation as they work. Background runs keep working after control returns to you and can be checked later.

Visibility is handled in the TUI rather than by log files alone. A persistent FleetView below the editor keeps active work visible, and /subagents-fleet opens a live inspector where you can browse children, read transcripts, steer a running child, or stop a run. You can also ask in plain language: "Show me the current async runs." The observability doc covers lifecycle artifacts, events, logs, and session sharing, which is where the machine-readable side of a run lives if you want to consume it outside the TUI.

Bounded orchestration is a separate concern from concurrency. maxSubagentSpawnsPerRun limits cumulative logical children in one run tree, defaults to 64, and stays separate from active concurrency and the session-wide cumulative spawn budget. That distinction is the interesting part: you can cap how many children a single tree may ever create without capping how many run at once. For a fan-out of parallel reviewers, the spawn cap is the number that will bite first.

Installing pi-subagents and running a first review

The README gives one required step, run through the pi CLI:

pi install npm:pi-subagents

After that, no agents, config, or slash commands are needed. You ask Pi in plain language and Pi decides whether to call the subagent tool, which agent to use, and how to compose the work. A first real use is a diff review:

Use reviewer to review this diff.

The reviewer agent is described as code review and small fixes against the task or plan, tests, edge cases, and simplicity. Because it is a foreground run, progress streams in the conversation and the result comes back there. If you want the work to continue while you do something else, ask for it in the background instead.

When the setup itself looks wrong, the README points at a diagnostic:

/subagents-doctor

or the equivalent natural-language request: "Check whether subagents and intercom are set up correctly." For help tied to the installed version, /subagents-guide [topic] takes a topic, with overview as the default and workflows, agents, missions, observability, tool-reference, configuration, models, watchdog, and extension-api as the others. The tool form is subagent({ action: "guide", topic: "workflows" }).

The six builtin agents and what each one is for

The extension ships with agents that work immediately, and the README gives each a one-line purpose. scout does fast local codebase recon: relevant files, entry points, data flow, risks. researcher does web and docs research with sources and a concise brief. worker does implementation work, edits files, validates, and escalates unapproved decisions instead of guessing. reviewer checks code and small fixes. 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 rule of thumb in the README maps them to a sequence: 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. The recommended loop for implementation work is clarify, scout, worker, fresh reviewers, worker.

The oracle and delegate split is the one worth thinking about. oracle is deliberately read-only, which is what makes it useful as a challenge to a plan you have already formed. delegate is the opposite: close to the parent, general purpose, and less specialized. If you find yourself reaching for delegate often, that is a signal the task does not need a specialized child at all.

Orchestration patterns, saved workflows, and the council shortcuts

Beyond single delegations, the README lists natural-language patterns: run reviewers for correctness, tests, and cleanup in parallel; run a review loop with a maximum of three rounds; have worker implement an approved plan and then run reviewers and apply the feedback; scout the auth flow before planning; run a saved workflow such as "Run the review chain on this branch."

The package includes /council and council-mode, plus documented model-based council-* profile examples that you add in your own agent directory. The council pattern is for material decisions you want debated by advisors rather than reviewed by one child. Packaged prompt shortcuts like /parallel-review and /review-loop make the repeated patterns repeatable, and the workflows doc covers orchestration patterns, scripted workflows, worktree isolation, child-to-parent coordination, and the recursion guard.

The recursion guard is the detail that tells you the authors expect nesting. A delegation layer that can spawn children from children needs a stop condition, and the fact that it is documented as its own concern is a sign the design takes runaway trees seriously. The same goes for worktree isolation: if a worker edits files, running it in an isolated worktree is the difference between a reviewable change and a mess in your working tree.

Where pi-subagents is the wrong tool

The clearest limitation is stated by the README itself: no automatic reviewer starts on install. The extension is inert until a prompt or project instruction asks for a subagent. Anyone who wants a mandatory review gate enforced by tooling will not get it here. The enforcement has to live in your prompts or project instructions, which means it can be forgotten.

Cost and latency are the second constraint. Every subagent is a child session doing its own work, and a parallel fan-out multiplies that. The spawn cap, maxSubagentSpawnsPerRun at a default of 64, is a bound, not a budget. Nothing in the README suggests a token or cost ceiling for a run tree, so a wide review loop is bounded by child count rather than by spend.

Third, the extension is Pi-specific. It is a Pi package, installed through the pi CLI, and its observability is built around the Pi TUI. If your work happens in another editor or agent harness, the delegation model here does not transfer. And if the task is small enough that you can read the diff yourself, a child session adds a round trip and a summary to read on top of the diff you were going to read anyway.

Alternatives and the difference in approach

The obvious alternative is to stay in one session and ask Pi directly. That is the right choice for small diffs and short tasks. The difference is context: one window holds everything, so the plan, the diff, and the review compete for the same space. pi-subagents trades that for a child session with its own context and a result brought back. The cost is orchestration: you now have runs to track, and the README's own answer to tracking is FleetView and /subagents-fleet.

A second alternative is a general multi-agent framework that wires agents together as a graph or pipeline in code. Those put the topology in a program you maintain. pi-subagents puts it in natural language and lets Pi decide whether to call the tool and how to compose the work, with scripted workflows and saved chains available when you want the pattern fixed. If you need a deterministic pipeline that behaves identically on every run, prompt-driven composition is a weaker guarantee than a coded graph, and the workflows doc is where you would check how much determinism the scripted path actually offers.

A third option is a code review bot attached to a pull request. That reviews after the code is pushed, outside your editing session. pi-subagents runs inside the session, before you summarize, which is a different point in the loop. The README's suggested instruction, "When you finish implementing, run a reviewer subagent before summarizing," is exactly that positioning.

Maintenance, licensing, and what a version bump costs you

The repository is not archived. The last push was on 2026-08-28, the same day as the v0.59.0 release, and v0.58.0 and v0.57.0 landed on 2026-08-27 and 2026-08-26. That is a fast release cadence, and the package.json in the repository shows version 0.67.0, which is ahead of the newest listed release, so the published release list lags the repository. Treat the CHANGELOG as the source of truth for what changed between the version you installed and the one you are upgrading to.

The licence is MIT, stated in package.json and present as a LICENSE file at the repository root. MIT is permissive, so the practical implication is that you can use, modify, and redistribute the extension with the copyright notice and licence text retained. That is a description of the licence terms, not legal advice; if you are redistributing it inside a commercial product, read the LICENSE file and your own policy.

Upgrade cost is the part the README does not document. There is no rollback procedure in the README, no stated compatibility matrix between extension versions and Pi versions, and no deprecation policy for agent frontmatter or the subagent tool parameters. The docs directory has a configuration and a tool-reference page, so the parameters are documented, but the README does not say what happens to a saved workflow or a custom agent when the tool signature changes. If you maintain custom agents in your own agent directory, pin a version and read the CHANGELOG before bumping.

Editorial conclusion

Adopt pi-subagents if you already run Pi and want review, scouting, or parallel audits done by a separate child session with its own context, started from plain language rather than a config file. Skip it if you expect an automatic reviewer to appear after install, or if you need a delegation layer for an editor other than Pi, since the extension is built around Pi's session model and installs through the pi CLI. Before relying on it, verify three things in your own setup: that /subagents-doctor reports the extension and intercom as configured, that a foreground reviewer run streams back into the conversation, and that maxSubagentSpawnsPerRun fits your workflow, because at its default of 64 a wide fan-out of parallel reviewers can hit the ceiling in one run tree.

Frequently asked questions

Official sources

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