Async subagents for pi, running in Herdr tabs, Orca terminal tabs, or tmux panes. Spawn a sub-agent, keep working in the main session, and get the result steered back when it finishes. Fully non-blocking.

The backend is selected automatically: Herdr is used when Pi runs in a Herdr-managed pane (HERDR_ENV=1), then Orca when Pi runs in an Orca-managed terminal (ORCA_TERMINAL_HANDLE), otherwise tmux is used when available.

How it works

subagent() returns immediately. In Herdr, the sub-agent runs in a new unfocused tab in the current workspace. In Orca, it runs in a new unfocused terminal tab in the current worktree, started in the parent Pi's working directory. In tmux, it runs in a right split off the parent Pi pane. A live widget above the input tracks every running sub-agent, and when one finishes, its result is steered into the main session as a notification that triggers a new turn.

Subagents 2 running
  ⟳ 00:23  scout      active · bash 7m
  ○ 00:45  scout-2    waiting 2m

Spawn several in parallel — they run concurrently and steer results back independently as each finishes.

Running subagents survive a parent /reload. Their terminal sessions and completion watchers stay active, then rebind result delivery and the status widget to the fresh Pi extension runtime. Replacing or closing the parent session still cancels its running subagents. This lifecycle behavior requires Pi 0.68 or newer.

tmux panes are kept evenly sized: the extension re-applies an even-horizontal layout after every spawn and exit (debounced). The layout is a single constant, SUBAGENT_TMUX_LAYOUT in pi-extension/subagents/tmux.ts — change it to any named tmux layout (main-vertical, tiled, …). Herdr and Orca subagents use separate tabs, so they do not resize the parent tab.

If your shell startup is slow and launch commands get dropped before the prompt is ready, raise the delay:

export PI_SUBAGENT_SHELL_READY_DELAY_MS=2500   # defaults: Herdr 1000, Orca 500, tmux 500

Tools

Tool	Description
`subagent`	Spawn a sub-agent in a dedicated terminal surface (async)
`subagent_message`	Message a sub-agent by name — steers it if running, resumes its session if finished
`subagents_list`	List available agent definitions
`ask_question`	(sub-agent sessions only) Ask the orchestrator a question and wait for the reply

There is also a /subagent <agent> <task> command for spawning directly.

Spawning

subagent({ agent: "scout", task: "Analyze the auth module" });
subagent({ agent: "worker", name: "dark-mode", task: "Implement the dark mode toggle" });

Parameter	Type	Default	Description
`agent`	string	required	Which agent to spawn (must be known and permitted)
`task`	string	required	Task prompt
`name`	string	agent name	Display name for the pane and widget. Must be unique — duplicates are auto-suffixed (`scout`, `scout-2`, …)
`model`	string	agent's model	Override the model for this spawn
`cwd`	string	agent's `cwd`	Working directory (see Role folders)

Messaging

subagent_message is addressed by name only. Names are unique per session and persist after a sub-agent finishes, so the same name works either way:

subagent_message({ name: "scout", message: "Also check the auth middleware" });

Running — the message is typed into the live pane (newlines flattened) and picked up at the next turn boundary. The call returns immediately; the eventual completion still arrives as a steer message.
Finished — the session is resumed with the message as the follow-up task, like a fresh spawn: fire-and-forget, always autonomous, result steered back later. The resumed run reclaims its original name.

Every spawn records name → session file in artifacts/<sessionId>/subagent-registry.json, so names stay addressable across pi restarts. A nested sub-agent that spawns children gets its own registry keyed by its own session id. Resume is refused with a clear error (listing known names) if the name isn't registered, the session file is gone, or the session predates sandboxed resume.

Resume replays the original sandbox. At spawn time the fully-resolved loadout — tool allowlist, backing extensions, model, thinking level, system prompt, spawn whitelist, cwd — is snapshotted to <session>.loadout.json. Resume rebuilds the exact same restricted process from that snapshot rather than relaunching unrestricted.

ask_question

A sub-agent can ask its orchestrator a single freeform question when requirements are ambiguous or a decision materially affects the work. The session stays open (parked as waiting) instead of exiting; the parent is notified with the sub-agent's name, replies via subagent_message({ name, message }), and the reply arrives as the sub-agent's next turn. Parallel questions are supported — each waiting sub-agent has its own name.

If the reply arrives while the sub-agent is still mid-turn, it is absorbed into the current turn — either way the question is marked answered and the session exits normally when the work is done. If the parent never replies, the pane stays open until a human closes it. Only available inside sub-agent sessions.

Bundled agents

Agent	Model	Tools	Role
scout	`openai-codex/gpt-5.6-luna` (`xhigh`)	`read`, `grep`, `find`, `ls`	Fast read-only codebase recon
researcher	`openai-codex/gpt-5.6-luna` (`xhigh`)	`web_search`, `web_fetch`, `safe_bash`	Web research, synthesized into a sourced brief
worker	`openai-codex/gpt-5.6-luna` (`xhigh`)	`read`, `write`, `edit`, `bash`, `web_search`, `web_fetch` + spawning	General implementer; may spawn `scout` and `researcher`

All three are autonomous (auto-exit: true) and carry their identity in the system prompt (system-prompt: append).

Custom agents

Place a .md file in .pi/agents/ (project) or ~/.pi/agent/agents/ (global). Discovery priority: project > global > package-bundled — a project-local file overrides a bundled agent with the same name.

---
name: my-agent
description: Does something specific
model: openai-codex/gpt-5.6-luna
thinking: xhigh
tools: read, edit, write, safe_bash, web_search
session-mode: lineage-only
auto-exit: true
---

You are a specialized agent that does X...

Frontmatter reference

Field	Type	Description
`name`	string	Agent name (used in `agent: "my-agent"`)
`description`	string	Shown in `subagents_list`
`model`	string	Default model
`thinking`	string	`minimal`, `low`, `medium`, or `high`
`tools`	string	Strict tool allowlist. Built-ins: `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`. Extension-backed: `web_search`, `web_fetch`, `safe_bash`, `video_extract`, `youtube_search`, `google_image_search`. Only the extensions backing the listed tools are loaded into the child
`subagent_agents`	string	Comma-separated agent names this agent may spawn. Presence of this field grants the spawning toolset (`subagent`, `subagent_message`, `subagents_list`) and restricts spawn targets to the list. Omit it and the agent cannot spawn at all
`skills`	string	Comma-separated skill names to auto-load
`session-mode`	string	`standalone` (default), `lineage-only`, or `fork` — see below
`system-prompt`	string	`append` or `replace`: pass the body as the child's `--append-system-prompt` / `--system-prompt`. Omit and the body is prepended to the task prompt instead
`auto-exit`	boolean	Auto-shutdown when the agent finishes (see below)
`interactive`	boolean	Whether stall/recovery transitions wake the parent (see below)
`cwd`	string	Default working directory
`disable-model-invocation`	boolean	Hide from `subagents_list`; still spawnable by explicit name
`cli`	string	`claude` runs the agent via the Claude Code CLI instead of pi

session-mode

standalone — fresh session, no lineage link to the caller (default)
lineage-only — fresh session with parentSession linkage for discovery/fork UX, but no copied turns
fork — child session seeded with the caller's conversation context

auto-exit

With auto-exit: true, the session shuts down when the agent's turn ends — the agent just writes its final message and stops (there is no "done" tool). The last assistant message becomes the summary returned to the parent. Recommended for all autonomous agents.

Notes:

Manual input does not strand an auto-exit sub-agent. If a human types into the pane, the session still closes once that turn completes normally — only an escape/abort leaves it open.
Auto-exit is suppressed while work is in flight: the session parks as waiting instead of exiting when an ask_question is still unanswered, or when the agent's own child sub-agents are still running (a worker can stop after dispatching children and stays open until the last result returns).

interactive

Controls whether stalled/recovered status transitions send a steer message to the parent session. Defaults to the inverse of auto-exit: autonomous agents get stall pings; user-driven agents stay quiet (the user is already working in that pane — the widget still updates). Set explicitly to override.

Tool access control

Access is whitelist-only. Every sub-agent process is launched with --no-extensions (extension discovery disabled) and --tools <allowlist>; only the extensions backing the listed tools are loaded back in explicitly. There is no default toolset and no deny-list — an agent gets exactly what its frontmatter lists. The restriction survives resume via the loadout snapshot.

Spawns must name a known agent at every depth. A top-level session may spawn anything discoverable; a sub-agent may only spawn the agents in its subagent_agents list (enforced via PI_SUBAGENT_ALLOWED). There is no agentless spawn route, so a child can never escalate to a full-toolset profile by omitting its agent.

Extensions can register additional tools for sub-agents at runtime via registerToolExtension(name, path) on the __pi_interactive_subagents process global. Hosts that compose widgets can optionally use its reload-safe statusWidget surface:

const { statusWidget } = globalThis.__pi_interactive_subagents;
const onChange = () => rerender();
const release = statusWidget.claim(onChange);

statusWidget.hasContent(); // whether any subagent rows exist
statusWidget.getBodyRowCount(); // uncapped number of running agents
statusWidget.render(width, maxBodyRows, ctx.ui.theme); // compact unboxed lines; cap includes an overflow row
statusWidget.isClaimed(onChange); // true only for the current provider claim
release(); // restore the standalone subagent-status widget

render(width, maxBodyRows?, theme?) accepts Pi's current theme as an optional structural value. The standalone widget receives and uses its own Pi theme automatically. When no theme is passed, a legacy ANSI fallback keeps status colors usable. The header is a compact unboxed Subagents <count> running row; body rows remain width-safe, and maxBodyRows counts body rows including the overflow summary, not the header. Semantic row colors match Pi's Todo conventions: accent header, muted count, warning active/running, error stalled, dim starting/provider tags/elapsed time, and accent waiting.

claim() replaces any prior claim, and an old release function cannot release a newer claim. Standalone-widget clearing/restoration is deferred to a microtask, so hosts may release and immediately re-claim without a transient fallback widget. isClaimed(onChange) checks both callback identity and the current runtime ownership, so hosts can detect invalidation after reload/session rebind. Claims are cleared during session shutdown, including /reload, so a fresh host runtime must claim again rather than retaining a stale callback. Calling render() directly does not claim or change the standalone widget.

Role folders

cwd starts a sub-agent in a directory with its own config, so role-specific setups (CLAUDE.md, skills, extensions) apply:

project/
└── agents/
    ├── game-designer/   ← CLAUDE.md, .pi/…
    └── sre/             ← CLAUDE.md, .pi/…

subagent({ agent: "worker", cwd: "agents/sre", task: "Review the deployment pipeline" });

Set a per-agent default with cwd: in frontmatter.

The widget tracks each sub-agent from a runtime activity snapshot written by the child: starting, active (turn/provider/tool work), waiting (open for input or another stage), stalled (no valid snapshot for too long), or running (fallback). Sub-agent sessions also show their own tools widget — toggle it with Ctrl+Alt+O. Completion messages expand with Ctrl+O.

Status display is configured via config.json in the extension directory (copy config.json.example; it's gitignored):

{
  "status": { "enabled": true }
}

Install

pi install npm:@jbcode/pi-interactive-subagents

Requirements

Pi
One supported terminal manager:
- Herdr, with Pi launched inside Herdr
- Orca, with Pi launched inside an Orca-managed terminal
- tmux

Herdr requires no extension configuration once its Pi integration is installed. The extension detects HERDR_ENV=1 and creates subagents as unfocused tabs in the current workspace.

Orca requires no extension configuration either. The extension detects ORCA_TERMINAL_HANDLE and creates subagents as unfocused terminal tabs in the current worktree via the orca CLI (ORCA_CLI_COMMAND is honored when set). New tabs start in the parent Pi's working directory with a bash shell.

For tmux:

tmux new -A -s pi 'pi'

Acknowledgements

Forked from HazAT/pi-interactive-subagents, which originated the subagent architecture, the multi-multiplexer surface layer, and the status widget; its supervision features were inspired by RepoPrompt.

License

MIT

README.md

Forked from amosblomqvist/pi-interactive-subagents

pi-interactive-subagents