# pi-subagentura — Pi subagents

> pi-subagentura is an open-source Pi extension for direct sub-agent tools, reusable workflows, and routing-first delegation to attachable interactive specialists.

## What it is

pi-subagentura is the flagship subagent system from subagentura. It keeps the parent Pi session in control while making child work inspectable, attachable, and recoverable. Version 3.4.1 supports three control surfaces in one extension.

### Routing-first delegation — `--orchestratorv2`

Run `pi --orchestratorv2` to route clear work to attachable interactive specialists. Broad or ambiguous scope stays visible until the parent can clarify it. The parent branch is authoritative for routing metadata; project-local state is repairable cache data. Interactive artifacts, pending deliveries, and completion receipts can rehydrate within the matching parent session.

## See the thin-router flow

Two real HTML replays show the Orchestratorv2 session tree:

- [Open the parent replay](https://htmlpreview.github.io/?https://gist.githubusercontent.com/lmn451/7da0271b7e863c1a215e2b7aec822c18/raw/index.html) — one user talks with a lightweight Orchestratorv2 parent while it fans work out to many attachable child sessions.
- [Open the child-session replay](https://htmlpreview.github.io/?https://gist.githubusercontent.com/lmn451/e4570ecfd640872efeeed72630d08f37/raw/index.html) — that child creates two interactive specialists, a recovery-safety reviewer and a package/API reviewer, and supervises them in its own conversation.

This is the core v2 model: you can keep talking with the orchestrator, attach and talk directly with a child, or let a child create and supervise its own nested descendants. Important outcomes flow back through the child and the parent’s artifact and notification paths. The replays were generated with [vibe-replay](https://github.com/tuo-lei/vibe-replay).

## Modes: keep every control surface

Start with `--orchestratorv2` for intent-based routing; nothing else is removed.

### Direct tools — no flag

Call in-process, interactive, and workflow tools directly. Choose inherited or isolated context, asynchronous or blocking execution, and the exact child you want.

### Reusable workflows — `--orchestrator`

Use the original bundled orchestration guidance for repeatable planning, review, research, and implementation workflows. Workflows can compose `agent()`, `parallel()`, and `pipeline()` phases with explicit boundaries.

## Pi subagents comparison

This comparison is a published-docs snapshot from July 2026. YES means explicitly documented, PARTIAL means a related but not exact capability, and NO means it was not found in the published documentation.

| Capability | pi-subagentura | HazAT pi-interactive-subagents | nicobailon pi-subagents | tintinweb pi-subagents | mjakl pi-subagent |
| --- | --- | --- | --- | --- | --- |
| In-process delegation | YES | NO | NO | YES | NO |
| Attach from another terminal | YES | YES | NO | NO | NO |
| tmux + Zellij child panes | YES | YES | NO | NO | NO |
| Follow up in a live child session | YES | PARTIAL | YES | YES | YES |
| Immutable per-turn output snapshots | YES | NO | PARTIAL | NO | NO |
| Automatic restart / reload rehydration | YES | PARTIAL | PARTIAL | PARTIAL | PARTIAL |
| Bundled orchestration defaults | YES | YES | YES | NO | NO |

## Install

```sh
pi install npm:pi-subagentura
```

For one routing-first session without a permanent install:

```sh
pi -e npm:pi-subagentura --orchestratorv2
```

## Canonical sources

- [Product page](https://subagentura.tech/pi-subagentura/)
- [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)
- [Changelog](https://github.com/lmn451/pi-subagentura/blob/master/CHANGELOG.md)
- [Orchestratorv2 routing guide](https://github.com/lmn451/pi-subagentura/blob/master/ORCHESTRATOR_V2_SYSTEM_PROMPT.md)
- [Workflow guide](https://github.com/lmn451/pi-subagentura/blob/master/docs/workflows.md)