pi-crew

Non-blocking subagent orchestration for pi. Run isolated subagents in parallel while your current session stays interactive. Updates return automatically to the session that started them.

Preview

Install

From npm:

pi install npm:@melihmucuk/pi-crew

From git:

pi install git:github.com/melihmucuk/pi-crew

This installs the extension, orchestration skill, prompt templates, and bundled subagents. pi-crew requires Pi 0.82.1 or newer.

How It Works

Once installed, pi-crew exposes these capabilities in your pi session:

Tools

crew_list

Lists available subagents and the active subagents owned by the current session, including each subagent's capabilities and whether it supports follow-up messages.

crew_spawn

Spawns a subagent in an isolated background session. Each spawn needs a short brief label and a structured, self-contained task. Results return automatically to the Pi session that started the work. If that session is inactive, results are queued for up to 24 hours.

{
  "subagent": "scout",
  "brief": "map authenticated API endpoints",
  "task": {
    "goal": "All authenticated API endpoints and their authentication methods are identified.",
    "context": ["The user needs this inventory before changing the authorization model."],
    "instructions": [
      "Find every API endpoint and trace its authentication checks.",
      "Report relevant paths, symbols, relationships, and discovery gaps."
    ]
  }
}

goal states the required end result, context carries task-relevant owner-session facts unavailable to the isolated subagent, and instructions lists the concrete task-specific actions. Put approved plans in instructions verbatim, or reference their readable source file. In the TUI, expand the crew_spawn tool call to review the complete task as rendered Markdown.

crew_abort

Aborts one, many, or all active subagents owned by the current session.

Supported modes:

• single: subagent_id
• multiple: subagent_ids
• all active in current session: all: true

"abort scout-a1b2"
"abort scout-a1b2 and worker-c3d4"
"abort all active subagents"

crew_respond

Sends a follow-up message to an interactive subagent owned by the current session that is waiting for a response. Interactive subagents stay alive after their initial response, allowing multi-turn conversations.

"respond to planner-a1b2 with: yes, use the existing auth middleware"

crew_done

Closes a waiting interactive subagent when you no longer need follow-up messages.

"close planner-a1b2, the plan looks good"

Prompt Templates

/pi-crew-plan

Expands a bundled prompt template that orchestrates discovery and planning for implementation tasks. Use it to spawn scout subagents to investigate the codebase, then delegate to a planner subagent to produce a step-by-step implementation plan.

The required scout and planner definitions are bundled with pi-crew.

/pi-crew-review

Expands a bundled prompt template that orchestrates parallel code and quality reviews. Use it to review provided or default changed-code scope with code-reviewer and quality-reviewer, using structured tasks that carry intent, expected behavior, and relevant references, then merge both results into one report.

The required code-reviewer and quality-reviewer definitions are bundled with pi-crew.

Skills

pi-crew

A bundled orchestration skill for writing self-contained tasks, coordinating parallel work, handling results, and managing interactive subagents.

Bundled Subagents

pi-crew ships with six subagent definitions that cover common workflows:

Subagent	Purpose	Tools	Interactive
scout	Discovers and maps relevant code. Read-only; not for review or planning.	read, bash	No
planner	Creates implementation plans. Read-only; use only when the user asks for a plan.	read, bash	Yes
oracle	Advises on high-impact decisions and trade-offs. Read-only; not for routine review or planning.	read, bash	Yes
code-reviewer	Reviews code changes for bugs and correctness. Read-only.	read, bash	No
quality-reviewer	Reviews code changes for maintainability and complexity. Read-only; use only when this focus is requested.	read, bash	No
worker	Implements and verifies code changes. Not for review, discovery, or planning.	all built-ins	Yes

Read-only bundled subagents still keep bash for inspection workflows like git and ast-grep. This is an instruction-level contract, not a sandbox boundary.

Subagent Discovery

Subagent definitions are discovered from three locations, in priority order:

1. Project: Pi's project config agents directory (default: <cwd>/.pi/agents/*.md)
2. User global: Pi's agent directory (default: ~/.pi/agent/agents/*.md)
3. Bundled: shipped with this package

When multiple sources define a subagent with the same name, the higher-priority source wins. This lets you override any bundled subagent by placing a file with the same name in your project or user directory.

Custom Subagents

Create .md files in Pi's project config agents directory (default: <cwd>/.pi/agents/) or global agent directory (default: ~/.pi/agent/agents/) with YAML frontmatter:

---
name: my-subagent
description: What this subagent does
model: anthropic/claude-haiku-4-5
thinking: medium
tools: read, grep, find, ls, bash
skills: skill-1, skill-2
---

Your system prompt goes here. This is the body of the markdown file.

The subagent will follow these instructions when executing tasks.

Frontmatter Fields

Field	Required	Description
name	yes	Subagent identifier. No whitespace, use hyphens.
description	yes	Shown in crew_list output.
model	no	provider/model-id format (e.g., anthropic/claude-haiku-4-5). If omitted, uses the owner's current model.
thinking	no	Thinking level: off, minimal, low, medium, high, xhigh, max.
tools	no	Comma-separated list or YAML array of built-in or extension-registered Pi tool names. Omit for all built-ins; use an empty value or list for none.
skills	no	Comma-separated list or YAML array of skill names (e.g., ast-grep). Omit for all; use an empty value or list for none.
compaction	no	Enable context compaction. Defaults to true.
interactive	no	Keep session alive after response for multi-turn conversations. Defaults to false.

Subagents use the owner's Pi model configuration and credentials. A configured model must be available under its exact provider/model-id; otherwise the subagent fails before sending a prompt. The owner's current model is used only when the model field is omitted. Custom tools are available when their registering extension is also loaded in the child session; pi-crew itself is excluded to prevent recursive delegation.

Subagent Overrides via JSON

You can override selected frontmatter fields without editing the .md definition files.

Config locations follow Pi's directories:

• Global: <agentDir>/pi-crew.json (default: ~/.pi/agent/pi-crew.json)
• Project: <cwd>/<CONFIG_DIR_NAME>/pi-crew.json (default: <cwd>/.pi/pi-crew.json)

Project config overrides global config. Only these fields are overridable:

• model
• thinking
• tools
• skills
• compaction
• interactive

name and description cannot be overridden.

Example:

{
  "agents": {
    "scout": {
      "model": "anthropic/claude-haiku-4-5",
      "tools": ["read", "bash"],
      "interactive": false
    },
    "planner": {
      "thinking": "high"
    }
  }
}

Override values replace the matching frontmatter fields for the named subagent after discovery. Unknown subagent names and invalid override values are ignored with warnings in crew_list output.

Status Widget

When the current session owns active subagents, the TUI shows their task labels, model and thinking settings, cumulative input/output tokens and cost, tool-call count, and recent tool activity.

On session replacement paths such as /new, /resume, /fork, and /reload, subagents keep running and reconnect when their owner session becomes active again. Quitting Pi aborts active subagents.

⏳ planner-e5f6 - plan config changes | Ctrl+Shift+E  expand
  6 tool calls · ↑ 16.4k · ↓ 2.2k · $0.05 · gpt-5.4 high
  ---
  read  README.md

↑ and ↓ show cumulative input and output tokens for the child session; $ shows its cumulative cost. Interactive subagents waiting for a response show a ⏳ icon. Ctrl+Shift+E toggles between the latest three and latest ten tool calls.

Acknowledgments

Inspired by these projects:

• pi-subagents by @nicobailon
• pi-interactive-subagents by @HazAT

License

MIT