Zero-config background subagents for Pi.
Most multi-agent frameworks are overengineered: task graphs, complex DAGs, message brokers, and hundreds of lines of YAML. pi-subagents does one thing: it lets your agent delegate work to a child Pi session in-process, inherit the parent's environment, and report back when finished.
When working on complex projects, you often need to run independent tasks in parallel:
- Research an unfamiliar library or API without polluting your main context.
- Run a deep code review or test suite in the background while continuing active work.
- Have two agents explore competing implementations of the same feature simultaneously.
- Split a large refactor across independent modules without merge conflicts.
pi-subagents gives the LLM one focused tool: subagent for delegation. Valid model IDs are injected into the session prompt each turn, so no separate discovery tool is needed.
- Zero configuration: The child session automatically inherits your active model, thinking budget, active tools, and working directory.
- In-process & fast: No Docker containers or background daemons. Children run as lightweight Pi agent sessions inside the same process.
- Synchronous by default: Subagents block and return their (capped) result directly in the tool response. Dispatch as many children in parallel as you need; per-child and batched result caps keep parent context growth predictable.
- Bounded results: Output budgets scale with the model's context window (up to 16 KB per child and 32 KB per batched delivery) to keep parent context growth predictable.
- Session replacement is coordinated:
/reload,/new,/resume, and tree navigation are blocked while subagents are running;/reloadwaits up to 10s for them to finish. Stop them with/subagents kill allwhen replacement must happen immediately.
pi install git:github.com/Bukutsu/pi-subagentsFor code audits, questions, investigations, or sequential work:
{
"prompt": "Find where authentication tokens are verified and check for expiration edge cases"
}The child investigates using read, bash, grep, etc., and returns its findings directly to the parent conversation.
Children inherit the parent’s current model by default. Each turn, the extension injects the current model and the session's available/scoped model IDs into the prompt, so pass an exact ID directly:
subagent({
"prompt": "Review the authentication flow for security issues",
"model": "provider/model-id"
})
Pass a different model only when reasoning ability, context size, cost, or input modality materially affects the task; invalid or out-of-scope IDs are rejected with the available names in the error.
When multiple subagents need to write or edit code at the same time, running them in the same workspace causes race conditions and file collisions.
Set worktree: true to give the child an isolated Git worktree on a dedicated branch (pi-subagents/<timestamp>-<id>):
{
"prompt": "Refactor src/storage.ts to use SQLite instead of JSON files. Run tests to confirm it passes.",
"worktree": true
}pi-subagentsverifies that your working directory is clean before creating the branch.- The worktree is created in private storage (
~/.pi/agent/pi-subagents/worktrees/), so your repository tree stays clean. - Once the child completes, inspect the diff and merge:
git diff HEAD..pi-subagents/1740000000000-a1b2c3d4 git merge --no-ff pi-subagents/1740000000000-a1b2c3d4 git branch -D pi-subagents/1740000000000-a1b2c3d4
If you want the subagent to run in the background without blocking the current turn:
{
"prompt": "Run full test suite and benchmark suite against all providers",
"background": true
}The child runs while you keep working. When it finishes, its result is delivered to this conversation as a new message that starts a turn automatically — so end your turn after dispatching and let the delivery wake you. Holding the turn open with sleep or polling is never needed.
| Parameter | Type | Default | Description |
|---|---|---|---|
prompt |
string |
required | Self-contained task instructions with context, file paths, and completion criteria. |
model |
string |
unset | Exact available provider/model ID; omit to inherit the current model. |
worktree |
boolean |
false |
Run in an isolated Git worktree; required for concurrent file writes. Omit for read-only tasks. |
background |
boolean |
false |
Run asynchronously in the background without blocking the current turn. |
sessionId |
string |
unset | Continue an existing session from an earlier result: resumes it when finished, or steers it with prompt while still running. |
stop |
boolean |
false |
With sessionId: interrupt that session. Reports terminal state instead of erroring if it already finished. |
peek |
boolean |
false |
With sessionId: return its state, current activity, and last output without disturbing it. |
Model IDs listed in the prompt hint refresh every turn, so /scoped-models changes and provider availability are always current.
Manage running subagents directly from Pi:
/subagents— Open the interactive TUI management dialog to view active jobs (model, elapsed time, activity, cost) and stop them. The status widget above the editor links to it./subagent— Alias of/subagents./subagents kill <pid>— Stop a specific running subagent./subagents kill all— Cancel all running subagents and clean up resources immediately.
All subagent state is kept in private directories outside your project tree:
| Item | Path |
|---|---|
| Session records & index | ~/.pi/agent/pi-subagents/index/ |
| Durable transcripts | ~/.pi/agent/pi-subagents/sessions/ |
| Session locks | ~/.pi/agent/pi-subagents/locks/ |
| Active worktrees | ~/.pi/agent/pi-subagents/worktrees/ |
| Retained logs | ~/.pi/agent/pi-subagents/logs/ |
- Output safety: Parent-visible child output is capped at 400 lines with a byte budget that scales with the model's context window (max 16 KB per child). Truncated output is retained on disk up to 10 MB (first 10 MB kept); the parent-visible result keeps the tail.
- Recursive prevention: Child sessions load all your standard tools, but the
subagenttool itself is excluded inside children to prevent infinite recursion.
bun install
bun run check
bun testMIT