@e9n/pi-subagent

Parallel task delegation extension for pi. Spawn isolated pi subprocesses for single, parallel, chain, orchestrator, and pool-based agent workflows.

Features

• Single — delegate one task to a named agent subprocess
• Parallel — run multiple independent tasks concurrently; results stream back as they complete
• Chain — pipeline tasks where each step receives the previous output via {previous}
• Orchestrator — hierarchical agent trees where agents spawn and message each other autonomously
• Pool — long-lived agents with persistent context; send follow-up messages without losing state
• Agent discovery — reads agent definitions from ~/.pi/agent/agents/*.md and .pi/agents/*.md
• Extension isolation — subagents run with --no-extensions by default; whitelist only what's needed
• System prompt injection — injects available agents and usage patterns into the LLM context automatically
• Bundled skill — includes skill definitions for agent orchestration patterns

Setup

Add to ~/.pi/agent/settings.json or .pi/settings.json:

{
  "pi-subagent": {
    "maxConcurrent": 4,
    "maxTotal": 8,
    "timeoutMs": 600000,
    "model": null,
    "extensions": [],
    "blockedExtensions": []
  }
}

Key	Default	Description
maxConcurrent	4	Max subagents running in parallel
maxTotal	8	Max total subagents per session
timeoutMs	600000	Subprocess timeout in ms (10 min)
model	null	Model override for all subagents (null = use default)
extensions	[]	Extension paths whitelisted for all subagents
blockedExtensions	[see below]	Extensions subagents can never load. Default: pi-webserver, pi-cron, pi-heartbeat, pi-channels, pi-web-dashboard, pi-telemetry. pi-subagent is always blocked.

Tool: subagent

Delegate tasks to isolated pi subprocesses. Choose a mode by supplying the matching parameter.

Modes

Mode	How to invoke	Description
Single	{ agent, task }	Run one agent on one task
Parallel	{ tasks: [{agent, task}, …] }	Run multiple tasks concurrently
Chain	{ chain: [{agent, task}, …] }	Pipeline — each step gets {previous} output
Orchestrator	{ orchestrator: {agent, task} }	Root agent spawns and manages sub-agents autonomously
Pool: spawn	{ action: "spawn", id, agent, task }	Start a persistent agent
Pool: send	{ action: "send", id, message }	Send a follow-up message to a pool agent
Pool: list	{ action: "list" }	List all active pool agents
Pool: kill	{ action: "kill", id }	Kill a pool agent and its children
Pool: kill-all	{ action: "kill-all" }	Tear down entire pool

Key Parameters

Parameter	Type	Description
agent	string	Agent name (from discovered .md definitions)
task	string	Task prompt for the subagent
model	string	Model override for this invocation
thinking	string	Thinking budget: off, minimal, low, medium, high, xhigh
extensions	string[]	Extra extension paths to whitelist for this invocation
noTools	boolean	Run without file/bash tools
agentScope	string	Agent discovery scope: user, project, or both

Events

Event	Payload	Description
subagent:start	{ agent, task, trackingId }	Fired when a subprocess is spawned
subagent:complete	{ agent, trackingId, status, tokens, cost, durationMs }	Fired when a subprocess finishes

Install

pi install npm:@e9n/pi-subagent

License

MIT