$ cat ~/map/pi-orchestrator.md

pi-orchestrator

Strips the main agent down to a delegate tool that commands isolated, budgeted subagent workers.

extensions✓ Sep 3

pi install npm:@saifymatteo/pi-orchestrator

## TL;DR

An extension that turns the main agent into an orchestrator: tools are reduced to a keep-list and the only path to real work is delegate, which spawns isolated pi --mode rpc subagent children with turn budgets and a stall watchdog.

## Key points

• $A before_agent_start hook appends a delegation policy every turn, generated from the discovered fleet and the tools actually kept; setActiveTools re-applies the keep-list each turn to catch late-registered tools.
• $A tool_call gate blocks anything off the keep-list with guidance to delegate; delegate spawns `pi --mode rpc --no-session` children with PI_ORCHESTRATOR_CHILD=1, and children self-disable the extension.
• $delegate takes three shapes: {agent, task} for a single job, tasks[] (max 8, concurrency 4) for independent parallel work, and chain[] with a {previous} placeholder for dependent steps.
• $Turn budgets steer softly at the limit and hard-kill at budget + 5 turns; a stall watchdog hard-kills a child silent for stallTimeoutMs (default 10 minutes), with any output resetting it.
• $Child success is state-based via the RPC agent_settled event — exit codes are informational only, since settled children are SIGTERMed by design.
• $Requires pi 0.84 or newer; configuration lives in ~/.pi/agent/orchestrator.json (enabled, keepTools, childBlockedTools, and friends).

## FAQ

## References

• README ↗

Last updated: Sep 3, 2026