# pi-subagentura — Pi subagents

> Interactive Pi specialists you can watch, steer, and continue with in a normal terminal session.

pi-subagentura is an open-source Pi extension for people who already use Pi with a terminal multiplexer. Give a specialist a task, watch its separate Pi session, then join that session when you need to redirect the work or continue the conversation. Supply task-specific persona instructions, and choose a configured Pi model when you need a different model for the child.

## Install and requirements

Published release: **3.6.4**, verified September 27, 2026.

```sh
# Try it for one session
pi -e npm:pi-subagentura

# Or install it for future sessions
pi install npm:pi-subagentura
```

Pi 0.80.6 or newer and Node.js 22.23.2 or newer are required. Interactive sessions use tmux, Zellij, or Herdr. Run Pi in the supported terminal environment to open specialists in panes or tabs. The optional in-process delegation tools do not create attachable terminal sessions.

## Two ways to coordinate

**Lead interactive specialists directly.** Give a specialist a focused task, inspect its current work, and focus or attach to its terminal. Send a follow-up to continue with that session’s existing context. A child can ask for clarification and can supervise its own bounded descendants.

**Enable the optional Orchestratorv2 parent coordinator.** Start Pi with `--orchestratorv2` when you want the parent to route clear work to interactive specialists. Ambiguous scope remains with the parent until it can ask you to clarify. Orchestratorv2 guides the parent through a system prompt; it is not a deterministic router or an enforced tool-permission boundary.

The original `--orchestrator` mode and reusable workflows remain available as advanced features. See the [workflow guide](https://github.com/lmn451/pi-subagentura/blob/master/docs/workflows.md) for saved scripts and workflow composition.

## Watch a session

- [Watch the complete 97:56 session as an 8:06 edited recording](https://subagentura.tech/media/pi-subagentura/workflow.mp4). Quiet stretches are accelerated up to 100×; the original terminal remains visible.
- [Read the English transcript](https://subagentura.tech/media/pi-subagentura/workflow.english-transcript.md).
- [Open the parent-session replay](https://htmlpreview.github.io/?https://gist.githubusercontent.com/lmn451/7da0271b7e863c1a215e2b7aec822c18/raw/index.html): a user talks with a lightweight parent while it delegates to child sessions.
- [Open the child-session replay](https://htmlpreview.github.io/?https://gist.githubusercontent.com/lmn451/e4570ecfd640872efeeed72630d08f37/raw/index.html): that child creates and supervises two interactive specialists.
- [See the replays and full walkthrough](https://subagentura.tech/pi-subagentura/#session-replays).

The recording shows tmux. The replays show the parent and child session flow; neither demonstrates a human attaching to the terminal. Check the requirements above for supported interactive backends.

## Lifecycle and context

Interactive children have their own Pi session context and durable artifacts. Artifacts and pending delivery can rehydrate when continuing the matching parent session through reload, resume, or quit transitions. Starting a fresh `/new` or `/fork` cleans up interactive work owned by the previous session. In-process jobs and background workflows are session-scoped and do not share the interactive-child recovery behavior.

Interactive children are separate processes, not isolated Git worktrees. Use worktrees separately when changes need their own checkout. Persona instructions are appended to the child system prompt; this does not import arbitrary agent-definition files, tool policies, or plugins.

## Pi subagents comparison — documentation checked September 27, 2026

Choose based on how you want agents to appear and coordinate. This comparison reflects published documentation, not hands-on benchmarks; features and package releases can change.

| Option | A good fit when | Interaction and tradeoff |
| --- | --- | --- |
| **pi-subagentura** | You want to direct interactive specialists yourself, or optionally ask a Pi parent to route tasks. | Separate attachable Pi sessions in tmux, Zellij, or Herdr; can continue a child and inspect per-turn artifacts. Interactive use requires Pi, a supported multiplexer, and Node.js. |
| [**HazAT/pi-interactive-subagents**](https://github.com/HazAT/pi-interactive-subagents) · npm [`@adamjen/pi-interactive-subagents`](https://www.npmjs.com/package/%40adamjen/pi-interactive-subagents) | You want asynchronous specialist panes and its bundled planning/iteration flows. | Supports cmux, tmux, Zellij, and WezTerm, with custom agent files, model overrides, interruption, and session resume. Also requires a supported multiplexer. |
| [**nicobailon/pi-subagents**](https://github.com/nicobailon/pi-subagents) · npm [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) | You want a broad orchestration toolbox for foreground and background child sessions. | Includes agent definitions, chains, parallel work, worktrees, scripted workflows, and FleetView for inspecting, steering, and resuming work inside Pi. |
| [**tintinweb/pi-subagents**](https://github.com/tintinweb/pi-subagents) · npm [`@tintinweb/pi-subagents`](https://www.npmjs.com/package/%40tintinweb/pi-subagents) | You want Pi agent fleet controls and scripted workflows. | Provides live progress, agent conversation views, mid-run steering, custom agent types, worktree isolation, and workflow scripts; its current README requires Pi 0.84.0 or newer. |
| [**mjakl/pi-subagent**](https://github.com/mjakl/pi-subagent) · npm [`@mjakl/pi-subagent`](https://www.npmjs.com/package/%40mjakl/pi-subagent) | You want headless specialist sessions with named continuation. | Runs child Pi processes whose named persistent sessions are scoped to the parent; it supports parallel calls and streams progress into the TUI. Requires Pi 0.80.6 or newer. |

**Adjacent team coordination:** [pi-messenger](https://github.com/nicobailon/pi-messenger) coordinates peer Pi sessions through a shared project workspace, with presence, messaging, file reservations, and Crew planning and execution. It focuses on team coordination between sessions rather than parent-to-specialist delegation.

## Sources

- [Source repository](https://github.com/lmn451/pi-subagentura)
- [npm package](https://www.npmjs.com/package/pi-subagentura)
- [README](https://github.com/lmn451/pi-subagentura/blob/master/README.md)
- [Orchestratorv2 routing guide](https://github.com/lmn451/pi-subagentura/blob/master/ORCHESTRATOR_V2_SYSTEM_PROMPT.md)
- [Reusable workflow guide](https://github.com/lmn451/pi-subagentura/blob/master/docs/workflows.md)
- [Product page](https://subagentura.tech/pi-subagentura/)