Pi subagent

Let Pi delegate tasks to helper agents. Each one runs as a separate Pi process with its own fresh context. Run reviewers in parallel, keep a worker around for follow-up tasks, and answer its questions while it works.

Install

pi install npm:@lwlee2608/pi-subagent

Run /reload if Pi is already open. Requires Node.js 22.19+ and Pi 1.x on Linux or macOS. Windows is not supported.

Don't install it alongside another extension that provides a subagent tool. Only one can load at a time.

Use

Ask Pi in plain language:

Use a reviewer to review the local diff.

Run three reviewers in parallel: one for correctness, one for tests, one for security.

Start a worker in ../my-worktree to implement the plan, then keep it around for review feedback.

Pi starts the workers, waits for them, and brings their results back. A compact panel above the editor shows progress while they run.

Things to know:

• Each worker starts with fresh context. It does not see your conversation, only the task Pi gives it.
• A worker can ask Pi a question mid-task. Pi answers it, or you can answer from the inspector.
• By default a worker exits after one task. Ask Pi to keep it if you want to send follow-up tasks.
• Stopping a worker never deletes its edits or transcript.
• Worktrees and Git are up to you (or Pi). This extension never creates or removes them.

Bundled agents

Both use your current model and thinking level unless you set one.

Custom agents

Add Markdown files to ~/.pi/agent/agents/. A file with the same name as a bundled agent replaces it.

---
name: reviewer
description: Reviews changes without modifying files
tools: read, bash, grep, find, ls
model: provider/model:high
---
System prompt for the agent.

A model or effort Pi passes for one task overrides the agent file.

Project agents in .pi/agents/ are ignored unless the project root is listed in trustedProjectRoots (see below).

Not a sandbox: tool lists are instructions, not OS isolation. An agent with bash can still modify files.

Configuration

Optional. Create ~/.pi/agent/pi-subagent/config.json:

{
  "extensions": { "provider": "/absolute/path/to/provider-extension.ts" },
  "trustedProjectRoots": ["/absolute/path/to/project"],
  "maxActive": 4,
  "maxWorkers": 16
}

Inspector

Press ↓ on an empty prompt while the panel is showing, or run /subagents, to open a live view: workers on the left, grouped with the reviewers nested under them, and the selected worker's transcript on the right.

Storage

Sessions and results are saved under ~/.pi/agent/pi-subagent/, readable only by you. Quitting Pi or running /reload closes all workers. Workers kept for follow-ups can be recovered later from the same Pi session.

License

MIT