---
Spawn sub-agents on demand with custom identities, models, and thinking levels. Watch them work live in a dedicated TUI that keeps your main conversation clean.
## โจ Features
- **๐งฌ Ad-hoc spawning** โ Define sub-agent identity inline per call (no markdown files, no registry)
- **๐ Isolated context** โ Each sub-agent runs in a separate `pi` process with `--no-session`
- **๐ Live TUI spying** โ Watch tool calls stream in real-time with a three-tier UI
- **๐ Three-tier UI** โ Scrollback row, bottom widget counter, interactive overlay panel
- **โก Concurrent execution** โ Run multiple sub-agents in parallel (PI runs tool calls concurrently)
- **๐ Abort support** โ Kill running sub-agents with `Escape` or `k` in the panel
- **๐ค PI-native** โ Seamless integration with PI's tool system, abort-signal aware, themed output
## ๐ฆ Installation
PI discovers the extension automatically once installed as a pi package. By default this installs globally into `~/.pi/agent/`; pass `-l` to install into the current project (`.pi/`) instead.
**From npm (recommended):**
```bash
pi install npm:@the-forge-flow/sub-agents-pi
```
**From GitHub (tracks `main`):**
```bash
pi install git:github.com/MonsieurBarti/sub-agents-pi
```
**Pin to a specific version:**
```bash
# npm โ pin to a published version
pi install npm:@the-forge-flow/sub-agents-pi@0.1.0
# git โ pin to a release tag
pi install git:github.com/MonsieurBarti/sub-agents-pi@sub-agents-pi-v0.1.0
```
Then reload PI with `/reload` (or restart it). On the next session you should see a notification that sub-agents is ready.
**Manage installed packages:**
```bash
pi list # show installed packages
pi update # update non-pinned packages
pi remove npm:@the-forge-flow/sub-agents-pi
pi config # enable/disable individual extensions, skills, prompts, themes
```
> For project-scoped installs, package filtering, and more, see the [pi packages doc](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/packages.md).
## ๐ Usage
### Basic invocation
Ask your LLM to delegate work:
```
Use the tff-subagent tool with system_prompt "You are a fast codebase scout. Return file:line refs with one-line summaries." and task "Find all JWT parsing code" and model "claude-haiku-4-5" and label "jwt-scout"
```
The `tff-subagent` tool spawns a child process that runs independently. You'll see:
- **Scrollback row** โ Compact status with live tool calls, final summary after completion
- **Bottom widget** โ Counter showing running/done sub-agents (`๐งฌ sub-agents 2 running ยท 1 done`)
- **Overlay panel** โ Rich interactive view opened with `ctrl+shift+s`
> The tool is namespaced as `tff-subagent` so it can coexist with other pi packages (such as `pi-superpowers-plus`) that also ship a `subagent` tool. The user-facing display label still shows as "subagent" / your custom `label` โ only the LLM-facing tool id is prefixed.
### Opening the spy panel
Press `ctrl+shift+s` to open the interactive sub-agents panel:
- **โโ** โ Navigate between sub-agents
- **Enter** โ Zoom into selected sub-agent's detail view
- **k** โ Kill selected running sub-agent (with confirmation)
- **Escape** โ Close panel (or exit zoom mode)
The panel shows a two-pane view: list of sub-agents on the left, live detail on the right. Tool calls stream in real-time, usage stats update live.
### Tool parameters
| Parameter | Required | Description |
|-----------|----------|-------------|
| `task` | โ
| The task prompt to send to the sub-agent |
| `system_prompt` | โ
| The sub-agent's identity/instructions |
| `label` | Optional | Short display name for the TUI (default: `"subagent"`) |
| `model` | Optional | Model id (e.g., `claude-sonnet-4-5`). Defaults to parent's model. |
| `thinking` | Optional | Thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` |
| `cwd` | Optional | Working directory for the child process |
| `tools` | Optional | Builtin tool allowlist (e.g., `["read", "grep", "bash"]`) for sandboxing |
### Read-only scout example
Create a sandboxed scout that can only read and search:
```
Use the tff-subagent tool with system_prompt "You are a read-only scout. Find all authentication-related code and return file:line refs." and task "Map the auth surface area" and model "claude-haiku-4-5" and tools ["read", "grep", "find", "ls"] and label "auth-scout"
```
The sub-agent won't be able to write files, edit code, or run bash commands โ perfect for safe reconnaissance.
## ๐ก Safety guardrails
**Nested sub-agents are disabled.** Only the top-level pi can spawn sub-agents โ sub-agents cannot themselves call the `subagent` tool. This is enforced at two layers:
1. **Registration-level:** when a child pi loads this extension, it detects `PI_SUBAGENT_DEPTH โฅ 1` and skips `registerTool` / `registerShortcut` entirely. The sub-agent's LLM never sees `subagent` as an available tool.
2. **Executor-level (fallback):** `MAX_SUBAGENT_DEPTH = 1` means any invocation from inside a sub-agent process returns a structured failure: "Nested sub-agent spawning is disabled." This only fires if the tool is somehow invoked programmatically, bypassing extension registration.
This prevents fork-bomb scenarios from confused or hostile prompts, and keeps reasoning about sub-agent lifecycles simple (the pool only ever holds a flat level of jobs).
**cwd validation.** If you pass a `cwd` that doesn't exist on disk, the tool returns `"cwd does not exist: 
