pi-subagents

pi-subagents lets Pi delegate work to focused child agents. Use it for code review, scouting, implementation, parallel audits, saved workflows, background jobs, and anything else that benefits from a second or third set of model eyes.

https://github.com/user-attachments/assets/702554ec-faaf-4635-80aa-fb5d6e292fd1

This is a fork — see FORK.md for fork policy and docs/fork-delta.md for the upstream delta ledger.

Install

pi install npm:@rhinos0608/pi-subagents

If the upstream npm:pi-subagents package is already installed, remove it first with your Pi extension manager: Pi identifies npm packages by name, so both copies could load and register the same tools twice. That is the only required step. For local development from a checkout, install the working tree directly instead:

pi install /path/to/Pi-Subagents

Background children use the host's SDK: npm Pi keeps its detached Node runner; the official Pi 0.86.1 Linux x64 standalone release loads the same runner through Pi's embedded SDK, without a separate SDK install. See Standalone background execution for the supported boundary and validation gate.

Try this first

You do not need to create agents, write config, or learn slash commands. After installing, ask Pi in plain language:

Use reviewer to review this diff.

Ask oracle for a second opinion on my current plan. Challenge assumptions and tell me what I might be missing.

Use scout to understand this code based on our discussion, then ask me clarification questions.

Run parallel reviewers: one for correctness, one for tests, and one for unnecessary complexity.

That is enough to start. Pi decides whether to call the subagent tool, which agent to use, and how to compose the work.

How it works

Pi is the parent session. 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. Foreground children run as sessions inside the parent Pi process and stream in the conversation. Background children run as sessions inside a detached runner process that keeps working and can be checked later.

Installing the extension does not start an automatic reviewer in the background. The subagent tool is available whenever the extension loads, and Pi can call it whenever delegation helps. Delegation policy is yours to set: if you want every implementation reviewed, or never want delegation without asking, say so in your prompt or project instructions:

When you finish implementing, run a reviewer subagent before summarizing.

Builtin agents

The extension ships with agents you can use immediately:

Rule of thumb: scout before you understand the code, researcher before you trust external facts, evidence-auditor before you rely on important research, worker to implement, reviewer to check, and oracle when the decision itself feels risky.

Common workflows

The package includes /council and council-mode, plus documented model-based council-* profile examples that you add in your own agent directory.

For implementation work, the recommended loop is clarify → scout → worker → fresh reviewers → worker. Packaged prompt shortcuts like /parallel-review and /review-loop make these patterns repeatable — see Workflows.

Where running work shows up

Foreground runs stream progress in the conversation. Background runs keep working after control returns to you.

In the TUI, a persistent FleetView below the editor keeps active work visible. /subagents-fleet opens a live inspector where you can browse children, read transcripts, and steer, interrupt, or stop a run. The Agents view lists agents and supports create, edit, delete, and disable; run details show cwd, budgets, worktree/branch, delivery, fallback-attempt history, and policy blocks. You can also just ask: "Show me the current async runs."

Details, keybindings, and the machine-readable run artifacts are in Observability.

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. See Configuration.

If something feels off

/subagents-doctor

or ask: "Check whether subagents and intercom are set up correctly."

For installed-version help, use /subagents-guide [topic] or subagent({ action: "guide", topic: "workflows" }).

Documentation

The full reference lives in docs/: