pi-subagents-team

Build and route your pi subagent team from one dashboard. Create, edit, and delete agent profiles — by hand, or by describing what you want and letting your current model draft them — and assign each role a model and reasoning effort.

Works on top of the pi-subagents extension, which provides the subagent tool this extension routes.

Install

pi install npm:pi-subagents-team

Or straight from source:

pi install git:github.com/jnardiello/pi-subagents-team

Dependencies

You need pi with pi-subagents installed, an external editor ($EDITOR), and at least one authenticated model.

Use

Run /subagents-team inside pi:

| Key | Action | |-----|--------| | ↑ ↓ + Enter | pick a role, then pick its model from the catalogue | | Tab / Shift+Tab | cycle the role's reasoning effort in place | | N | create a profile — write it manually, or describe the intent and let the AI draft it, then confirm in your editor | | E | edit the selected profile: description, tools, permissions, system prompt, rename, raw file, or AI rewrite | | D | delete the selected profile | | B | toggle pi-subagents' builtin agents on/off | | Enter on SAVE | persist the assignments |

From then on everything is automatic: assignments are restored silently at every session start and injected into each subagent call (single, parallel, and chains); calls to a role without a model are blocked until you assign one.

Delegation guard

When pi's root agent starts doing investigation (read/grep/find/ls/bash) or edits directly, /delegation-guard nudges it to delegate instead — via a model-visible steer message that is delivered only while the run is still making tool calls (a nudge armed on the final answer is dropped, so it never spawns an extra turn) — and can optionally block root edits until a subagent has run in the turn. Fan-out enforcement nudges when independent subtasks are launched as sequential single spawns instead of one parallel {tasks:[...]} call, and when direct investigation continues heavily after a spawn (under-decomposed briefs):

| Arg | Effect | |-----|--------| | (none) / status | report current state | | on / off | enable / disable the guard | | nudge | nudge mode (default): steer messages, never blocks | | block-edits | also block root edit/write until a subagent ran this turn | | block | also block investigation calls (read/grep/find/ls/bash) past the threshold until a subagent runs; allowlist entries bypass the block | | fanout on / fanout off | fan-out enforcement (default on): nudge on 2+ sequential single spawns with no {tasks} fan-out or chain, and on more than 2× threshold direct investigation calls after a spawn | | threshold <n> | investigation calls that trigger the nudge/block (> n, default 3) | | allowlist add <prefix> | add an entry that bypasses block mode: a bash-command prefix (e.g. git status) or a tool name (e.g. read) | | allowlist remove <prefix> / allowlist clear | drop one entry / clear the list | | allowlist show | list current allowlist entries (also shown in status when non-empty) |

Settings persist in settings.json under delegationGuard (including investigationAllowlist, default []). The guard is dormant in child subagent sessions. Turn it off if you prefer to work directly.

Profiles are plain markdown files (YAML frontmatter + system prompt) in pi-subagents' user agents directory — you can always edit them directly.

Every new profile also carries a least-privilege permission: frontmatter block (picked via a capability checklist, or drafted by the AI from your intent) for the pi-permission-system extension — harmless when it is not installed. Unchecked capabilities are explicit denies, so headless subagents fail fast instead of stalling on an approval prompt.

Working on or with this repo through a coding agent? Point it at agents/ — it holds everything an AI agent needs to guide you through the plugin or to contribute changes.

License

MIT