nicobailon / pi-subagents

# 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.
## Install
 [code] 
That is the only required step. pi-subagents needs Pi 1.2.0 or newer. Background children use the host's SDK: npm Pi keeps its detached Node runner; the official Pi 1.2.0 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:
 [code] 
 [code] 
 [code] 
 [code] 
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. When the session's model can take a new tool mid-conversation, fresh parent sessions initially expose the small `subagents_enable` loader instead of the full `subagent` schema. When your request or applicable instructions authorize delegation, Pi can call the loader itself; the unchanged `subagent` tool is available on the next model request. With other models, fresh sessions start with `subagent` active, because adding a tool later would make the provider miss its prompt cache. The `toolActivation` setting changes this. Complexity alone does not authorize delegation. `bg_wait` and supervisor replies remain available without activation.
If you want every implementation reviewed, say so in your prompt or project instructions:
 [code] 
## Builtin agents
The extension ships with agents you can use immediately:
| Agent | Use it when you want... |
|-------|--------------------------|
| `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks. |
| `researcher` | Web/docs research with sources and a concise research brief. Requires pi-web-access in the child. |
| `evidence-auditor` | Independently checks whether important research claims are supported by their sources. Requires pi-web-access in the child. |
| `worker` | Implementation work. Edits files, validates, escalates unapproved decisions instead of guessing. |
| `reviewer` | Code review and small fixes against the task/plan, tests, edge cases, and simplicity. |
| `oracle` | A second opinion before acting. Challenges assumptions without editing. |
| `delegate` | A lightweight ge