pi-subagents: Claude Code style sub-agents inside a pi extension

What pi-subagents solves, and for whom

pi is a coding agent. Once a task needs several independent lines of work, a single conversation becomes the bottleneck: context from one investigation pollutes the next, and a long tool call blocks everything behind it. pi-subagents is a pi extension that attacks that directly. It spawns specialized agents in isolated sessions, each with its own tools, system prompt, model and thinking level, and runs them in the background by default. The intended user is someone already working inside pi who wants Claude Code style delegation without leaving that environment. The README is explicit that the tool names and calling conventions match Claude Code (`Agent`, `get_subagent_result`, `steer_subagent`), so the extension is also aimed at people carrying habits, or scripts, over from that tool. If you do not use pi, nothing here applies to you.

Isolated sessions, a concurrency queue, and group join

Each sub-agent gets its own session rather than a branch of the main conversation. That isolation is the mechanism behind most of the feature list: separate tools, separate model, separate thinking level, separate transcript. Agents run in the background by default and can be made to block instead. Spawning is queued against a configurable concurrency limit, default 10, so a burst of agents does not all hit the provider at once. The README describes smart group join, meaning notifications for a batch of agents are consolidated rather than delivered one by one. Nested sub-agents are opt-in and off by default. A custom agent that sets `allowed_subagents` receives its own ownership-scoped copies of the three agent tools, depth-capped from the main session with a default of 2. Children are stopped when the parent finishes, and their transcripts and token spend roll up to it. The README frames the allowlist as a privilege boundary, which is the right framing: a child runs with its own tools, so the list deserves the same scrutiny as `tools:`.

The SubagentWorkflow tool and its node:vm sandbox

Improvised orchestration is the failure mode this feature exists to prevent. `SubagentWorkflow` takes a deterministic JavaScript script and runs it, exposing `agent()`, `parallel()`, `pipeline()`, `phase()`, `log()` and `args`, plus a pure-literal `meta` block declaring the phases. The distinction between `parallel()` and `pipeline()` is the interesting design choice. `parallel()` idles every fast agent until the slowest finishes; `pipeline()` has no barrier between stages, so one item can advance while another is still in the first stage. `agent()` accepts `gate: "npm test"` to verify a child by running a command inside its worktree when isolated, rather than spending another model call on verification, and `resume: "<label>"` to continue a child instead of re-paying its context. The script runs in a `node:vm` sandbox on a worker thread where `Date.now()`, `Math.random()` and `eval` throw. That is a deliberate determinism constraint, and it means scripts that depend on wall-clock time or randomness will not port without rewriting. Scripts written for Claude Code's `Workflow` tool are claimed to run unchanged, with one documented difference: `budget` is present but always reports no token target, because pi has no such directive, so `budget.total`-guarded branches keep taking the path they were written for.

Custom agent types and the ambiguity fallback

Agent types are Markdown files with YAML frontmatter, placed in `.pi/agents/<name>.md` or `.agents/agents/<name>.md` for a project, or globally. The frontmatter carries the system prompt, model, thinking level, tool restrictions and a Claude Code compatible colored name badge. Type resolution is case-insensitive, so `explore`, `Explore` and `EXPLORE` all work. The fallback rule is where I would push back on the design. A type that does not resolve to exactly one enabled agent, whether unknown, disabled, or ambiguous between two agents differing only by case, falls back to general-purpose with a note. Silent substitution is convenient and also a quiet way to run the wrong prompt against the wrong tool set. If you define both `Explore` and `explore`, you get general-purpose and a note, not an error. Treat agent type names as a namespace you lint by hand.

FleetView, the widget, and steering a run mid-flight

The interactive surface is substantial. A persistent widget above the editor shows animated spinners, live tool activity, token counts and colored status icons, configurable through `/agents → Settings → Widget` as `all`, `background` (the default, which hides foreground runs because they already render inline as the `Agent` tool result) or `off`. FleetView renders `main` plus every running subagent below the editor, earliest launched first. Press `↓` or `←` at an empty prompt to jump in, `↑`/`↓` to move, `Enter` to open a live auto-updating conversation, `Esc` to return. Finished agents linger briefly, and a viewer stays open through completion so the final output remains readable. Inside the viewer, `Enter` opens a composer for mid-run steering, the message lands as a user message and redirects the agent after its current tool, and `x` followed by `x` stops a running agent, background runs included. Agent mentions add a second control path: typing `@explore also check the RPC path` routes text to that agent without it entering the chat, and the same syntax covers messaging a running agent, resuming a finished one, reopening a session from disk, or starting one that never ran. `@main` forces text back to the main model.

Getting it running: install, settings and the workflow opt-out

The package is published as `@tintinweb/pi-subagents` on npm and the repository is MIT licensed, with no archived status and a last push dated 2026-09-03. The README does not spell out the install command in the material I have, so the concrete entry points I can name are the configuration ones. Settings live under `/agents → Settings`, with widget mode, Fleet view and Agent mentions each toggled there. Persistent settings are written to `subagents.json`, and `workflowsEnabled` is the key that pins the workflow tool on or off. The concurrency limit defaults to 10 and is described as configurable, though the README excerpt does not name the key. One behaviour worth reading twice: the workflow tool is on by default but stands down for company. If another extension already provides a `Workflow` or `SubagentWorkflow` tool, this one warns and disables itself for the session rather than offering the model two orchestrators. That is a sensible collision policy and also a silent capability loss if you install a second orchestration extension and forget why scripts stopped running.

Limits, wrong fits, and how it differs from a general agent framework

The clearest constraint is the sandbox. No `Date.now()`, no `Math.random()`, no `eval`. Workflow scripts are reproducible by construction, and any script that needs a timestamp or a random seed has to be rewritten to pass those values in. The second constraint is depth. Nested sub-agents are off by default and depth-capped at 2 from the main session, so deep delegation trees are not on the menu. The third is the ambiguity fallback described above. The wrong tool case is straightforward: if your orchestration must run outside pi, from a CI job or a server process, this extension is not that. It is a pi extension, and the entire surface (widget, FleetView, `/agents` menu, mentions) assumes an interactive pi session. The natural alternative in the same space is Claude Code's own `Workflow` tool, and the difference is mostly one of containment rather than capability. Claude Code's workflows execute in that product; pi-subagents executes them in a `node:vm` sandbox on a worker thread with the three globals above throwing, and adds a compatibility shim for `budget` so existing `budget.total` branches behave. If you already have Claude Code workflow scripts and use pi, the port cost is close to zero, which is the strongest argument the README makes.

Maintenance cost and what to check before adopting

The release cadence visible in the material is tight: v0.18.1 on 2026-08-24, v0.18.2 on 2026-08-25, v0.19.0 on 2026-08-27, with the last push to master on 2026-09-03. Frequent minor releases at 0.x mean the surface is still moving, and the configuration keys are the part most likely to shift under you. Budget for reading release notes before upgrading rather than pinning and forgetting. The MIT licence is permissive and imposes no copyleft obligation on your own code, but the repository's own licence file is the authority and this is not legal advice. Before adopting, confirm the concurrency key name and its default of 10 against your provider's rate limits, check whether anything else in your pi install already exposes a `Workflow` tool, and audit your `.pi/agents` directory for case-colliding filenames so you do not silently get general-purpose where you expected `explore`.

Editorial conclusion

Adopt pi-subagents if your work already happens inside pi and you want sub-agents with named custom types, background execution and a deterministic script path. Do not adopt it if you need agent orchestration outside pi, or if you cannot accept that a child agent inherits a real tool surface from a YAML allowlist. Verify first that the concurrency limit of 10 matches your provider rate limits, that the workflowsEnabled setting does not collide with another extension exposing a Workflow tool, and that your custom agent frontmatter resolves to exactly one enabled type, since ambiguity silently falls back to general-purpose.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tintinweb/pi-subagents on GitHub