pi-subagents

A pi coding agent extension that lets the agent spawn specialized subagents — each running in its own isolated session with its own model, tools, and instructions.

Install

pi install npm:@piotr-oles/pi-subagents

Agent templates

Define agents as markdown files with YAML frontmatter. Two locations are supported:

Location	Scope
~/.pi/agent/subagents/<name>.md	Global — available in all projects
.pi/subagents/<name>.md	Project — available in current project only

A project template overrides a global template with the same name.

Example .pi/subagents/coder.md:

---
description: Specialist for writing and editing code
model: anthropic/claude-opus-4-5
thinking: low
max_turns: 30
included_tools: bash, read, edit, write
---

You are an expert software engineer. Focus only on the assigned task.
Write clean, well-tested code. Do not ask for clarification — make reasonable assumptions.

Frontmatter fields:

Field	Type	Description
description	string	Short description shown in the UI. Defaults to the filename.
model	string	Model to use (e.g. anthropic/claude-haiku-4-5). Inherits from parent session if omitted.
thinking	string	Thinking level: off, minimal, low, medium, high, xhigh.
max_turns	number	Hard turn limit. When reached the agent is given grace turns to wrap up.
grace_turns	number	Extra turns after max_turns before the agent is force-stopped.
enabled	boolean	Set to false to disable this agent type without deleting the file.
included_tools	string	Comma-separated list of tool names available to this agent. Omit to inherit all tools from the parent session.
included_skills	string	Comma-separated list of skill names available to this agent. Omit to inherit all skills.
included_subagents	string	Comma-separated list of subagent template names this agent may spawn.

If no matching template is found the agent falls back to general-purpose, or a plain default if that is also absent.

Tools

subagent

Spawns a subagent to handle a task, or follows up on a previously completed one.

Parameter	Type	Description
name	string	Name of the agent template to use. Required for both spawn and follow-up.
id	string	ID of a done subagent to follow-up. Omit when spawning fresh.
description	string	Short description of the task (shown in UI).
prompt	string	Task prompt sent to the subagent.

Blocks until the subagent completes and returns its result inline. To follow up on a finished subagent, call subagent again with the id returned in the previous result plus a new prompt.

How it works

1. On before_agent_start, templates are reloaded from disk.
2. When subagent is called, the extension resolves the template, builds an AgentConfig, and starts an isolated pi session.
3. The subagent session inherits the parent's model registry and working directory but gets its own system prompt built from the template's instructions.
4. The subagent tool is excluded from subagent sessions unless included_subagents is set — only then can a subagent spawn further subagents (limited to the listed templates).
5. A concurrency queue limits how many agents run simultaneously; excess agents are queued and started as slots free up.

Flags

pi --pi-subagents-max-concurrent 4    # max agents running at once (default: 4)

Or via environment variable:

PI_SUBAGENTS_MAX_CONCURRENT=2 pi

subagent:templates command

Opens an interactive menu listing all loaded agent templates with their source (global ◦ / project •) and model. Run via the pi command palette.

Development

pnpm install
pnpm test
pnpm typecheck
pnpm check

To test changes manually, pass the source entry point directly to pi:

pi -ne -e packages/pi-subagents/src/index.ts