pi-subagents

Codex-style multi-agent orchestration for pi. Spawn, communicate with, and coordinate sub-agents via LLM tool calls.

Sub-agents are invisible child pi --mode rpc processes. No terminal multiplexer required, no TUI overlay. The LLM orchestrates everything through 5 tools.

Install

pi install npm:pi-agents-pool

Or from git:

pi install git:github.com/minghinmatthewlam/pi-subagents

Tools

| Tool | Description | |------|-------------| | spawn_agent | Spawn a sub-agent with a task. Returns immediately with an agent ID; the agent runs in the background and notifies the main session when done. | | send_input | Send a follow-up message to an existing agent. Supports interrupt to redirect work. | | wait_agent | Block until one or more agents finish. Use only when the main session is blocked on the result right now. | | close_agent | Shut down an agent. Can be resumed later. | | resume_agent | Resume a previously closed agent from its saved session. |

How It Works

Recommended flow:

1. LLM calls spawn_agent("Analyze the auth module")  -> returns agent ID immediately
2. LLM calls spawn_agent("Analyze the DB module")    -> returns another agent ID
3. LLM keeps doing local non-overlapping work
4. Finished agents steer results back automatically via <subagent_notification>
5. LLM reads results, integrates, continues

wait_agent is the exception path, not the default path. Use it only when the main session is blocked on a result and must pause.

When an agent finishes, the extension injects a <subagent_notification>...</subagent_notification> message and triggers a new turn automatically. That notification is an agent result, not a user message.

Each agent is a persistent pi --mode rpc child process with full bidirectional communication. The LLM can send follow-up messages, interrupt ongoing work, and reuse agents for related questions.

A widget above the input shows live progress:

2 agents (2 running)
├─ Analyze the auth module (explorer) · 3 tool uses · 12.4k tokens · 0:23
│  └ Read: src/auth/index.ts
├─ Analyze the DB module (explorer) · 1 tool use · 4.1k tokens · 0:15
│  └ thinking…

Agent Types

Agent types are purely advisory — they guide the LLM on when and how to use each role. There is no mechanical difference between types.

| Type | Guidance | |------|----------| | explorer | Fast codebase questions. Spawn multiple in parallel for independent questions. Trust results. Reuse via send_input. | | worker | Implementation tasks. Assign explicit file ownership. Tell workers they are not alone in the codebase. |

spawn_agent({ message: "What does the auth module do?", agent_type: "explorer" })
spawn_agent({ message: "Implement the login endpoint", agent_type: "worker" })

Depth Limiting

Sub-agents can themselves spawn further sub-agents, limited by depth:

• PI_SUBAGENT_MAX_DEPTH (default: 2) — maximum nesting depth
• Main session (depth 0) can spawn agents (depth 1), which can spawn sub-agents (depth 2), which cannot spawn further

Override:

export PI_SUBAGENT_MAX_DEPTH=3   # allow deeper nesting
export PI_SUBAGENT_MAX_DEPTH=1   # only one level of agents

Parameters

spawn_agent

| Param | Type | Required | Description | |-------|------|----------|-------------| | message | string | yes | Task prompt for the agent | | agent_type | string | no | Role hint: "explorer" or "worker" | | model | string | no | Override model (e.g. "anthropic/claude-haiku-4-5") |

send_input

| Param | Type | Required | Description | |-------|------|----------|-------------| | id | string | yes | Agent ID from spawn_agent | | message | string | yes | Message to send | | interrupt | boolean | no | Abort current work before sending |

wait_agent

Use only when you are blocked on a dependency and need to pause the main session until an agent finishes. On timeout, the agents keep running in the background.

| Param | Type | Required | Description | |-------|------|----------|-------------| | ids | string[] | yes | Agent IDs to wait for | | timeout_ms | number | no | Timeout (default: 30s, min: 10s, max: 1h) |

close_agent / resume_agent

| Param | Type | Required | Description | |-------|------|----------|-------------| | id | string | yes | Agent ID |

License

MIT