Clear work goes to a specialist.
The parent routes repository work to attachable interactive children and keeps intent at the top level.
Pi subagents, routed by intent.
Looking for Pi subagents? Start with--orchestratorv2: a thin parent that routes clear work to attachable specialists and keeps the user conversation focused. Direct tools and the original --orchestrator workflow mode remain available when those are the better fit.
v3.4.1Pi ≥0.80.6MITtmux + Zellij
FLAGSHIP / PI EXTENSIONv3.4.1 · READY
pi-subagentura
Routing-first parent control for clear work. Interactive children you can watch, re-enter, or talk to directly. Direct tools and reusable workflows remain available alongside it.
PRIMARY MODEORCHESTRATORV2
OTHER SURFACESDIRECT · WORKFLOW
interactive child · attachabletmux | zellij
pi install npm:pi-subagenturaRoute by intent.
START HERE / ORCHESTRATORV2A thin, prompt-directed router for attachable interactive children. It keeps the parent focused on the outcome while specialists handle the repository work in sessions you can re-enter.
LAUNCH
Read the routing guide pi --orchestratorv2Ambiguity stays visible.
When a request is too broad or has no matching child, Orchestratorv2 asks before it commits to a path.
The parent keeps the ledger.
The current parent branch is the authority for routing metadata; project-local state is repairable cache data.
The work can come back.
Interactive artifacts, routing state, pending deliveries, and receipts rehydrate within the matching parent session.
See the parent hand off the work.
These two real HTML replays make the routing model tangible: you give one outcome to the parent, the thin router fans work out to attachable children, and a child can create its own bounded specialist team.
SESSION GRAPH / REAL LINEAGEparent → child → nested
01 / INPUTYou
Give one outcome to the orchestrator.
02 / ROUTEROrchestratorv2 parent
Clarifies scope, then routes clear work.
PARENT FANS OUT / ATTACHABLE CHILD SESSIONS
CHILD 01Research
Inspect one bounded question.
CHILD 02Workflow child
Own a reusable implementation loop.
CHILD 03Review
Check the result and return a receipt.
CHILD 02 DELEGATES / IMMEDIATE DESCENDANTS
NESTED ARecovery safety
Review session continuity and failure paths.
NESTED BPackage / API
Check public behavior and integration edges.
OPEN THE REPLAYS
Follow the conversation, turn by turn.
The annotations mark the parent-to-child handoff and the two specialist launches. Open either replay in a new tab, then return here to compare the two levels of the session tree.
- REPLAY / 01Open parent replay
Parent session / thin router
One user talks with a lightweight Orchestratorv2 parent while it fans work out to many attachable child sessions.
EMBEDDED PREVIEW / PARENTHTML PREVIEW - REPLAY / 02Open child replay
Child session / nested team
That child creates a recovery-safety reviewer and a package/API reviewer, then supervises both in its own conversation.
EMBEDDED PREVIEW / CHILDHTML PREVIEW
Replays generated with vibe-replay, an interactive replay and sharing tool for AI coding sessions.
STEERING OPTIONS
One user. Three useful moves.
- Stay with the orchestrator. Keep the top-level outcome and let the parent coordinate the child sessions.
- Talk directly to a child. Attach to a live child and send follow-ups without restarting its context.
- Let a child go deeper. A child can create bounded descendants; important outcomes return through the child and parent delivery paths.
Keep every control surface.
Start with --orchestratorv2 for intent-based routing; nothing else is removed. Direct tools and the original--orchestrator guidance remain available for the jobs they fit best.
No flag. Your tools, your prompts.
Call in-process, interactive, and workflow tools directly. Choose inherited or isolated context, async or blocking execution, and the exact child you want.
piReusable process with --orchestrator.
Use the bundled orchestration guidance to turn a goal into a saved workflow for planning, review, research, or implementation loops.
pi --orchestratorRouting-first with --orchestratorv2.
Send clear work to attachable interactive specialists, split broad requests, and ask for clarification instead of guessing when scope is ambiguous.
pi --orchestratorv2Keep the original workflow mode.
--orchestrator remains the right entry point for reusable, agent-authored workflows with phases, fan-out, schemas, usage, and background controls.
Compose a reviewed process.
Use agent(), parallel(),pipeline(), and named phases in a reusable.mjs file. Intermediate results stay out of the parent context until the workflow completes.
Stay responsive while it runs.
Workflows and direct async jobs return an ID for status, results, and cancellation. Interactive children use tmux or Zellij by default, with an in-process fallback when no multiplexer is available.
Keep the boundaries honest.
Background jobs and workflows remain scoped to the parent session. Interactive artifacts can rehydrate with their matching parent, so persistence is explicit rather than implied.
Pi subagents: compare the control surface.
Most Pi extensions help you delegate. This comparison is a published- docs snapshot for the moment you need to watch the child, steer it, recover it, and keep a durable record.
Pi subagents comparison table
Published docs snapshot · July 2026YES explicitly documentedPARTIAL related, but not exactNO not found in docsIn-process = same Pi runtime · scroll →
| Feature | pi-subagenturalmn451 · this project | pi-interactive- | pi-subagentsnicobailon | @tintinweb/ | @mjakl/ |
|---|---|---|---|---|---|
| In-process delegationRuns the child in the parent Pi runtime. | YES | NO | NO | YES | NO |
| Attach from another terminalWatch and work in the child outside the parent pane. | YES | YES | NO | NO | NO |
| tmux + Zellij child panesUse the multiplexer you already run. | YES | YES | NO | NO | NO |
| Follow up in a live child sessionContinue the same child context without restarting it. | YES | PARTIAL | YES | YES | YES |
| Immutable per-turn output snapshotsInspect exactly what each completed turn produced. | YES | NO | PARTIAL | NO | NO |
| Automatic restart / reload rehydrationBring interactive children back with durable state. | YES | PARTIAL | PARTIAL | PARTIAL | PARTIAL |
| Bundled orchestration defaultsGuidance for planning, review, and workflows. | YES | YES | YES | NO | NO |
One install covers both worlds.
pi-subagentura combines direct in-process delegation with attachable interactive child sessions. Use the old workflow mode for repeatable processes, or add Orchestratorv2 when the parent should route by intent and keep the child work re-enterable.
Yes means the capability is explicitly documented. Partially means a related capability is documented, but not this exact workflow. No means we could not find it in the published documentation. Each package name links to the source used for this snapshot.
Use it globally, per project, or for one run.
Install the extension once, choose the mode that fits the task, and keep the source path one click away.
Install the package
Make all three control surfaces available to Pi.
Keep it local
Install only for the current project.
pi install -l npm:pi-subagenturaTry the router
Load the package for one Pi session without a permanent install.
pi -e npm:pi-subagentura --orchestratorv2