pi-subagent

Run and orchestrate specialised agents in separate conversations from Pi, backed by Pi or Claude. Fan out work in parallel, keep track of every Run from the live dashboard, and resume, steer, or cancel agents without interrupting your main conversation.

Install

pi install npm:@goofansu/pi-subagent

The package includes profiles for general work, implementation, specification review, and standards review.

Commands

| Command | Description | | --- | --- | | /subagent | Lists profiles and current work. | | /subagent dashboard | Opens the dashboard for live work, Run history, and read-only inspection. Press Alt+Shift+. to open it directly. | | /subagent doctor | Reports configuration and runtime problems. |

Tools

A subagent is a conversation that can continue across tasks. A Run is one task in that conversation.

| Tool | Description | | --- | --- | | agent_start | Creates a subagent and starts its first Run. | | agent_resume | Starts another Run in an idle subagent. | | agent_wait | Waits for named Runs and returns their results. | | agent_wait_all | Waits for all Runs active at the time of the call. | | agent_cancel | Requests cancellation and keeps partial output. | | agent_steer | Sends guidance to an active Run. | | agent_result | Returns a finished Run's full result. |

agent_start and agent_resume return IDs immediately. A completion notice contains the result when it fits. Use agent_result to read longer output.

Pi-backed subagents disable normal extension discovery so their Profile controls their model, prompt, and tools without arbitrary startup hooks changing them. The global exe-dev extension is the sole exception when installed, allowing subagents on exe.dev VMs to use the VM's provider routes and injected context. Models from Pi's built-in catalogue, including Radius, remain available; providers and tools from every other extension do not. Consequently, if a Profile omits its model while the parent uses another extension-defined provider, agent_start fails because that provider is unavailable to the child. Pin a built-in, exe.dev-provided, or models.json model in the Profile instead.

Agent profile format

To add an agent or replace a bundled one, create a Markdown file in ~/.pi/agent/agents/ (or $PI_CODING_AGENT_DIR/agents/ if configured). The filename is the agent name: reviewer.md defines reviewer. Profiles are not loaded from individual projects.

---
description: Reviews changes for bugs and missing tests
backend: claude
model: sonnet
effort: high
tools: Read, Grep, Glob
---

Review the changes. Report actionable bugs and missing tests with file references.
Do not modify files.

| Field | What to set | | --- | --- | | description | A short explanation of when to use this agent. Required. | | backend | pi (default) or claude. | | model | For Pi, a model ID or provider/model-id; omitted, it uses the caller's model. For Claude, use fable, opus, sonnet, or haiku; omitted, it uses Claude's default. Full Claude model IDs are not accepted. | | effort | off, minimal, low, medium, high, xhigh, or max. | | tools | A comma-separated list of tool names for that backend. Omit to use its defaults. Pi and Claude use different tool names. | | appendSystemPrompt | Defaults to true, adding the profile's instructions to the backend's standard instructions. Set false to replace them. |

The text below the frontmatter is the agent's required system prompt. Profiles are loaded and validated when the Session starts; invalid profiles are reported then. A same-name user Profile replaces the complete bundled Profile.

Trust and Claude settings

For the safest default, I recommend setting Pi's defaultProjectTrust to "never" in ~/.pi/agent/settings.json (or through /settings):

{
  "defaultProjectTrust": "never"
}

This declines trust when no saved decision applies; explicitly trust projects whose project-level settings and instructions you want subagents to load.

Pi resolves trust for the Session working directory. agent_start reads the decision through ctx.isProjectTrusted() and stores it in SubagentContext. The decision stays fixed for the subagent, including resumed Runs.

In a trusted directory, Claude loads its user, project, and local settings. In an untrusted directory, Claude loads only the user setting source. Project and local settings, instructions from those sources, and project .mcp.json are excluded. User MCP servers and cloud connectors remain available.

Claude bypasses permission prompts in both cases. Trust is not a sandbox. It does not restrict filesystem, shell, network, or other ambient access.