pi-actor-subagents

Build arbitrary agent hierarchies in Pi where every agent can message every other agent. Inspect their conversations and steer them directly. Agents survive Pi restarts.

Pairs well with pi-infinite-context for long-running conversations.

Install

Requires Pi 1.2.0 or newer.

pi install npm:pi-actor-subagents

Subagents panel

Click an agent in the roster to open its conversation. Inside the panel, click another agent or use ↑/↓ to switch. Click Esc at the top right, or press Escape, to close.

Mouse controls use Pi's fullscreen mode. /subagents and the keyboard controls also work without it. The input box messages the selected agent directly.

Tools

/subagents opens the panel. /subagents-pause, /subagents-resume, and /subagents-kill control named subtrees; omit names to target your direct children.

All tool results in the main session and subagents include start/finish timestamps, giving agents a sense of elapsed time for progress updates and ETA estimates. If a start time is unavailable, only the finish time is shown.

Configuration

Optional file: ~/.pi/agent/actor-subagents/settings.json (inside Pi's configured agent directory):

{
  "maxAgents": 8,
  "maxSpawnDepth": 3,
  "childExtensions": [
    "~/.pi/agent/npm/node_modules/pi-infinite-context/extensions/infinite-context/index.ts"
  ],
  "childExtensionStatusKeys": ["bash-async"]
}

• maxAgents: maximum live background agents (default: 8).
• maxSpawnDepth: maximum hierarchy depth (default: 3). Both limits must be positive integers; missing or invalid values use their defaults. Changes apply after restarting Pi.
• childExtensions: extension whitelist for subagents (default: []). List extension files or directories; children do not inherit Pi's discovered extensions. A listed extension's prompt guidelines reach subagents too, because a subagent's instructions are appended to Pi's own system prompt. Actor-subagents' orchestration tools are always available and need no whitelist entry. Changes apply to newly spawned agents. The example path assumes pi install npm:pi-infinite-context in the default Pi setup. Child extensions run unattended, with ctx.mode === "print" and ctx.hasUI === false, so they take their headless paths instead of asking. Their ctx.ui.setStatus texts still appear in the roster and in list_subagents when they set them unconditionally, not only when ctx.hasUI is true.
• childExtensionStatusKeys: status keys shown in the roster and in list_subagents of subagents (default: unset, which shows every key). Statuses with other keys are ignored. An invalid value shows every key. Changes apply to newly spawned agents.

Coordination

• Backbrief: for each task from its parent, a child is instructed to investigate briefly without changing anything, then send its parent the goal and done-criteria in its own words, numbered assumptions, a plan, the main risk and open questions, and wait for a send_message go-ahead before working. Stated assumptions surface gaps that questions alone miss: the parent recognizes a wrong assumption more easily than it recalls what it forgot to say. The parent can waive it in the task. This is an agent protocol, not an enforced scheduling barrier.
• Ownership: every agent controls the agents it spawns and their descendants; messaging and inspection are open to all. set_status is for background agents.
• Errors: a new child error sends its live direct parent a scheduler message: it requests a turn when idle, steers a busy parent, and buffers while the parent is paused or still stopping. It does not restart the child. Pause, resume and kill notices stay silent.
• Persistence: reopening the same saved main session restores agents paused; resume them explicitly. Buffered messages, progress, and ETA are not saved.