@pi-vault/pi-subagents

Delegate focused work to bundled Pi subagents — singly in the foreground, asynchronously in the background, or as multi-agent chains — without leaving your session.

Install

pi install npm:@pi-vault/pi-subagents

Reload Pi after install or upgrade:

/reload

Quick Start

Agent	Use it for
scout	Map a workspace, locate entry points, surface change surfaces.
researcher	Read code and docs to gather evidence, constraints, tradeoffs.
planner	Turn a task into a short, verifiable plan before implementation.
worker	Make focused, contained code changes and verify them.
reviewer	Review a diff for defects, regressions, and missing tests.

Run one inline to see it work:

/agent scout map the repository structure

---

Single Agent: /agent

The slash command runs an agent synchronously in the foreground. The result is delivered as a slash card with live tool activity, turn count, and thinking level while it runs.

/agent planner design a caching strategy for the API client
/agent worker add retry with exponential backoff
/agent reviewer review the staged diff

Background Execution

Pass --run_in_background to the subagent tool (from chat or from another agent) to launch an agent and continue working:

subagent {
  agent: "worker",
  task: "refactor the auth flow",
  run_in_background: true
}

You get an agent ID immediately and are notified on completion. While it runs:

• Use get_subagent_result(agent_id) to check status and retrieve the result.
• Use steer_subagent(agent_id, message) to redirect a running agent.
• Use wait({ id: "..." }) to block until a specific agent finishes, wait({ all: true }) for all, or wait() for the next one to complete.

Background completion notifications are deduplicated: retrieving a result with get_subagent_result automatically suppresses the queued nudge.

Parallel Batches

Fire several background agents in the same turn and, with defaultJoinMode: smart (the default), one grouped notification replaces N individual nudges:

/agent scout map the auth surface  --run_in_background
/agent researcher document the OAuth scopes  --run_in_background
/agent reviewer check the open PR for regressions  --run_in_background

Subagent Tool Parameters

Agents and chat both invoke the same subagent tool:

Parameter	Type	Notes
agent	string	Agent name (required).
task	string	Task to delegate (required).
cwd	string	Override working directory.
model	string	provider/id or fuzzy name (haiku, sonnet).
thinking	string	off, low, medium, high.
max_turns	number	Per-run turn cap. Overrides the agent default.
isolated	boolean	Drop extension/MCP tools; built-in tools only.
inherit_context	boolean	Fork the parent conversation into the agent.
run_in_background	boolean	Return an agent ID and stream progress as the agent runs.
resume	string	Agent ID to resume with new instructions.
isolation	string	worktree to run in a temporary git worktree.
tool_budget	object	Soft/hard limits for this invocation.
chain	array	Multi-step pipeline (see below).
chain_append	object	Append steps to a running chain.
clarify	boolean	Show step-editor TUI before chain execution.

---

Chains: Multi-Agent Pipelines

Chains let you sequence agents so later steps consume the output of earlier ones.

Inline /chain

/chain scout "find the rate limiter" -> planner -> worker --bg

Arrow-separates steps; task text goes in quotes. Trailing flags:

• --bg — run in background.
• --yes — skip the step-confirmation TUI.

Parallel Groups

Wrap sibling steps in parentheses separated by |:

/chain (scout "audit error handling" | researcher "find error patterns") -> worker --bg

Configure concurrency or isolation after the group with [concurrency=2, worktree].

Saved Chains

Bundled chains ship in the chains/ directory. Run one with /run-chain:

/run-chain implement -- <your task description>

Project chains go in .pi/chains/; user chains in your global agent dir. Chain files use .chain.md or .chain.json format.

Chain Status and Cancellation

/chain status          # list all running chains
/chain status <id>     # detail for one chain
/chain cancel <id>     # stop a running chain

Template Variables

Within a chain step, these variables are expanded automatically:

• {task} — the original task passed to the chain.
• {previous} — the output of the immediately preceding step.
• {outputs.<name>} — the output of a step named with as:.
• {chain_dir} — the temporary directory of the current chain run.

---

User Agents

User overrides live in ~/.pi/agent/agents/<slug>.md. Each file has frontmatter plus a prompt body.

---
name: my-worker
description: Focused implementation helper.
tools:
  - read
  - edit
  - write
  - bash
  - grep
  - find
  - ls
model: default
thinking: medium
prompt_mode: replace
max_turns: 20
enabled: true
inherit_context: false
run_in_background: false
isolated: false
extensions: true
subagent_agents:
  - scout
  - reviewer
memory:
  scope: user
  path: my-worker
tool_budget: { "soft": 15, "hard": 25 }
intercom: true
disallowed_tools:
skills:
---

You are My Worker.

Make the smallest safe change that completes the task, then verify.

Supported Frontmatter Fields

Field	Type	Notes
name	string	Optional display name; otherwise the filename slug is used.
description	string	Required short summary shown in /agents.
tools	list	Comma-separated string or YAML list. Built-in tools and subagent.
model	string	default falls back to the host session; otherwise provider/id or fuzzy name.
thinking	string	off, low, medium, high.
subagent_agents	list	Allowlist of child agents this agent may invoke.
skills	list / all / none	all, none, or a comma-separated/YAML list of skill names.
prompt_mode	replace | append	Default replace. append layers the agent prompt on top of the parent prompt.
max_turns	integer	Maximum turns before the agent is steered to wrap up. 0 means unlimited.
max_depth	integer	Maximum recursion depth for child-agent spawning. 0 means unlimited.
inherit_context	boolean	If true, fork the parent conversation into the agent.
run_in_background	boolean	If true, return immediately and run in background.
isolated	boolean	If true, the agent gets no extension/MCP tools, only built-ins.
isolation	worktree	Run the agent in a temporary git worktree.
extensions	true | false | list	true keeps all, false/none drops all, list is an allowlist.
disallowed_tools	list	Tools to remove from the agent's allowlist after extension filtering.
tool_budget	JSON object	{"soft": N, "hard": M, "block": ["tool1", ...]}.
memory	object	{"scope": "user"|"project"|"local", "path": "dir-name"}.
intercom	boolean	If true, child agents get the contact_supervisor tool.
enabled	boolean	false keeps the agent registered but suppresses invocation.

timeout_ms is no longer supported. Use max_turns.

---

/agents Menu

/agents opens an interactive menu with three sections:

Agents — list bundled agents and user overrides; create, edit, export, disable, or delete.

Settings:

Setting	Default	Notes
maxConcurrency	3	Max background agents running at once.
defaultMaxTurns	—	Default per-run turn cap when an agent does not set max_turns.
graceTurns	5	Extra turns after max_turns to let the agent wrap up cleanly.
defaultJoinMode	smart	async, group, or smart (default; batched for parallel agents).
widgetMode	background	all, background, or off — controls the activity widget.
fleetView	on	Show the below-editor fleet list of in-flight agents.
maxSpawnsPerSession	40	Total spawned agents before the session is blocked.

Back returns to the parent menu.

---

UI: Widget, Fleet, And Conversation Viewer

Three optional TUI surfaces sync with running agents:

• AgentWidget — activity sidebar above the editor; respects widgetMode.
• FleetList — below-editor navigator listing every in-flight agent; toggle with fleetView.
• ConversationViewer — overlay (Ctrl/Cmd+O) for reading the full transcript of any agent.

All three show live tool activity, turn count, and steered status.

---

Settings File

Settings merge from two locations (project overrides global):

• Global: ~/.pi/agent/subagents.json
• Project: .pi/subagents.json

{
  "maxConcurrent": 5,
  "defaultJoinMode": "smart",
  "widgetMode": "all",
  "fleetView": true,
  "maxSpawnsPerSession": 50,
  "toolBudget": { "soft": 30, "hard": 50 },
  "modelScope": {
    "enforce": true,
    "allow": ["anthropic/claude-sonnet-*", "openai/*"]
  },
  "watchdog": {
    "enabled": true,
    "model": "anthropic/claude-sonnet-4-20250514",
    "thinking": "medium",
    "reviewChangesOnly": true,
    "children": { "enabled": false },
    "autoFollow": { "blockers": true, "concerns": false, "maxAttempts": 2 }
  }
}

---

Watchdog

The watchdog is an optional post-review step that inspects an agent's changes (or its turn-by-turn conversation) after it finishes. Findings are surfaced as severity-categorized warnings in the TUI.

/watchdog                    # show current status
/watchdog off                # disable for this session
/watchdog recommend-model    # suggest a model for watchdog use

Configure via the watchdog key in settings (see example above). When autoFollow.blockers is true, the watchdog automatically steers the finished agent to fix issues found during review.

---

Prompt Workflows

Markdown templates with frontmatter that expand to agent tasks. Place them in ~/.pi/agent/prompts/ or .pi/prompts/:

---
description: Summarise the current diff
subagent: worker
---

Analyse the staged git diff and write a concise summary covering the purpose of each change.

/prompt-workflow summarize          # run with no arguments
/prompt-workflow review -- --scope auth   # pass arguments ($1, $@)

Chain multiple workflows:

/chain-prompts analyze -> fix -- scope auth

---

Intercom (Child↔Parent Communication)

When an agent has intercom: true in its frontmatter, it receives a contact_supervisor tool. The parent session gets an intercom tool to reply:

intercom { action: "list" }
intercom { action: "reply", replyTo: "...", message: "Proceed with your best judgment." }

---

Common Workflows

Find and fix a bug:

/agent scout trace where the cache TTL is computed
/agent worker fix the cache expiry bug
/agent reviewer review the staged diff

Chain the same sequence as a pipeline:

/chain scout "trace where the cache TTL is computed" -> worker -> reviewer

Research, then implement, in background:

/agent researcher analyse all error boundaries --run_in_background
/agent worker add error boundaries to the API layer --run_in_background

Iterate with a persisted agent override:

Create a custom agent via /agents, then run it with the same refined prompt every time.

---

Development And Verification

pnpm install
pnpm check          # lint + typecheck + test
pnpm release:check  # check + pack dry-run

Acknowledgement

@pi-vault/pi-subagents was inspired by and builds on ideas from

• nicobailon/pi-subagents
• tintinweb/pi-subagents

Thank you for laying the groundwork.

Changelog

See CHANGELOG.md for release notes.

License

MIT. see LICENSE.