pi-subagent

A Pi extension for delegating work to configurable sub-agents.

Give each sub-agent its own model, thinking level, instructions, and time budget. Pi can launch several at once, continue other work while they run, and receive each result automatically. A live fleet window lets you inspect, steer, stop, and review them without leaving the session.

Like this extension? See my other Pi extensions.

Requirements

• Pi 0.84.1 or later
• A model configured in Pi
• Node.js 22.19.0 or later for package development

Installation

From npm:

pi install npm:@arcanemachine/pi-subagent

From GitHub:

pi install git:github.com/arcanemachine/pi-subagent

For local development:

pi -e ./src/index.ts

Restart Pi after installation, or use /reload in an existing session.

Quick start

pi-subagent works without a sub-agent configuration. When pi-subagent.agents is missing or empty, use the built-in default type:

/subagent spawn:default Review these changes and report any problems

The default sub-agent uses the model and thinking level active in the current Pi session. Run /subagent to view, steer, stop, and review active sub-agents.

The default type is available only when no custom agent types are configured. Once you add custom types, use their names instead.

For different models, instructions, or session forks, define one or more custom agent types in Pi's global ~/.pi/agent/settings.json:

{
  "pi-subagent": {
    "agents": {
      "research": {
        "model": "provider/model",
        "thinking_level": "high",
        "when_to_use": "Research, source gathering, and focused investigation",
        "extra_context": "Stay focused on your work. Do not expand scope."
      }
    }
  }
}

Replace provider/model with a model available in your Pi configuration, then reload Pi. The command returns immediately. When the sub-agent finishes, its result is delivered back into the parent conversation automatically.

You can also ask Pi to delegate work naturally, for example:

Use the research sub-agent to investigate this API while you continue reviewing the implementation.

Commands

| Command | Action | | ---------------------------------------------------- | --------------------------------------- | | /subagent | Open the live sub-agent fleet | | /subagent fleet | Open the same fleet window | | /subagent spawn:<agent> [timeout:<seconds>] <task> | Start a configured sub-agent | | /subagent steer <id\|all> <guidance> | Redirect one or every running sub-agent | | /subagent kill <id> | Stop one running sub-agent | | /subagent killall | Stop every running sub-agent |

Agent names are exact configuration keys. A spawn request cannot override the configured model or session fork.

Live fleet

The fleet presents each sub-agent as a small, selectable Pi session. It shows the current activity, streamed response preview, elapsed time, context usage, and final result when available.

| Key | Action | | ----------------------- | -------------------------------------------- | | ↑ / ↓, j / k | Select a sub-agent | | Page Up / Page Down | Scroll the selected session | | s | Write guidance for the selected sub-agent | | x / X | Stop the selected sub-agent / all running | | r / R | Remove the selected result / all finished | | Escape | Cancel the current action or close the fleet |

Stopping and removal require confirmation. Starting and running agents can be steered or stopped; completed, errored, and stopped agents can be removed. The fleet retains the 20 most recent finished sessions without keeping their child processes alive.

Agent tools

These tools let Pi manage sub-agents from the conversation. You normally do not need to call them yourself.

| Tool | Purpose | | --------------------- | ----------------------------------------------------------- | | subagent_spawn | Start one configured sub-agent and return immediately | | subagent_list_types | List configured agent types and their usage guidance | | subagent_steer | Send follow-up guidance to one running agent or all of them | | subagent_status | Inspect structured live status when an update is needed | | subagent_kill | Stop one running sub-agent |

Sub-agents report completion automatically. Pi should never poll for progress or completion by any means, including status checks, sleep commands, or wait loops; subagent_status remains available for a one-time inspection rather than repeated waiting.

Configuration

The extension reads the pi-subagent namespace from Pi's normal settings files:

• Global: ~/.pi/agent/settings.json
• Project: <project>/.pi/settings.json

Trusted project settings are deep-merged over global settings, including individual agent properties. Project settings are ignored when the project is not trusted.

Agent types

Each entry under agents defines one agent type:

| Property | Required | Description | | ---------------- | -------- | ----------------------------------------------------------------------- | | model | Yes | Exact provider/model used by the child | | thinking_level | No | Child thinking level; inherits the parent's current level when omitted | | when_to_use | No | Description shown by subagent_list_types and spawn command completion | | extra_context | No | Additional instructions prepended to every task for this agent type | | fork | No | Pi session ID or snapshot path used as the child's starting context |

Supported thinking levels are off, minimal, low, medium, high, xhigh, and max. Pi may clamp a level that the selected model does not support.

A configured fork follows Pi's native --fork behavior. Relative paths are resolved from the project working directory. Forked agents create persistent child sessions; ordinary agents do not. Snapshots created by pi-session-snapshot can be used as fork sources.

Runtime controls

| Setting | Default | Behavior | | ------------------------------ | --------- | ------------------------------------------------------------------------ | | max_active_subagents | Unlimited | Reject new spawns after the configured concurrency limit is reached | | default_timeout_seconds | 180 | Give each child a default time budget and ask it to wrap up when reached | | allow_nested_subagents | false | Allow spawned children to use this extension's own sub-agent tools | | hide_default_subagent_footer | false | Hide the reminder shown below default-agent spawn messages |

max_active_subagents accepts positive integers up to 100. Requests above the limit are rejected rather than queued.

When the built-in default type is active, spawn messages show a short reminder about custom configuration. Set hide_default_subagent_footer to true to hide it. The reminder is shown only in the user-facing spawn display, not in the tool result sent to the model.

default_timeout_seconds is a finishing budget, not a hard process kill. The extension warns the child as the deadline approaches and asks it to submit its best available result when time expires. Use subagent_kill when a child must be stopped immediately. A spawn can override the budget with timeout_seconds in the tool or timeout:<seconds> in the command.

Nested sub-agents are disabled by default to prevent unplanned recursive fan-out. Enable them only when you explicitly want children to delegate further work.

Completion and lifecycle

Each child receives the child-only subagent_complete tool for returning its final deliverable. If it finishes with an ordinary final response instead, that response is used as a fallback. Empty, errored, aborted, or truncated responses are reported as failures rather than silently treated as complete.

Finished children leave active status automatically and remain available in the recent fleet history. Starting a new parent session stops the current children. Reloading the extension also stops them, but records an interruption message in the parent conversation so unfinished work is not mistaken for a task failure.

Activity and response previews are kept in bounded memory. Each sub-agent runs as a separate Pi child process; configured forks preserve the source session context, while ordinary tasks do not create persistent sessions.

Development

npm install --ignore-scripts --workspaces=false
npm run format:check
npm run typecheck
npm run test
npm run build
npm pack --dry-run

Pi loads the TypeScript entrypoint directly from src/index.ts; no compiled runtime artifact is required.

License

MIT