pi-crew

Coordinate AI agent teams inside Pi.

pi-crew is a Pi extension that orchestrates autonomous multi-agent workflows — research, implementation, review, testing, and more — with durable state, parallel execution, worktree isolation, and safe defaults.

npm: pi-crew
repo: https://github.com/baphuongna/pi-crew

v0.2.0: Security hardening + 76% faster startup. See CHANGELOG.md.

---

Features

• One Pi tool — team handles routing, planning, execution, review, and cleanup
• Autonomous delegation — policy injection decides when/how to delegate based on task complexity
• Real child Pi workers — each task spawns a separate Pi process by default; scaffold/dry-run opt-out
• Adaptive planning — implementation workflow lets a planner agent decide subagent fanout
• Parallel execution — tasks in the same phase run concurrently with configurable concurrency
• Durable state — manifest, tasks, events, artifacts all persisted to disk
• Async/background runs — detached runs survive session switches with completion notifications
• Worktree isolation — opt-in git worktrees per task for safe parallel edits
• Rich UI — live widget, dashboard, progress tracking, model/token display
• Observability — metrics registry, Prometheus/OTLP exporters, heartbeat watching, deadletter queue
• Resource management — create/update/delete agents, teams, workflows with validation
• Import/export — portable run bundles for sharing and archiving

---

Install

pi install npm:pi-crew

Local development:

pi install ./pi-crew

Post-install config bootstrap:

pi-crew          # after npm install
node ./pi-crew/install.mjs   # from local clone

---

Quick Start

1. Initialize project

/team-init

2. Run a team

/team-run Investigate failing tests and propose a fix

Or via tool call:

{
  "action": "run",
  "team": "default",
  "goal": "Investigate failing tests and propose a fix"
}

3. Check status

/team-status <runId>
/team-dashboard

4. Get a recommendation

When unsure which team/workflow fits:

{
  "action": "recommend",
  "goal": "Refactor auth flow and add tests"
}

---

Builtin Teams

Team	Workflow	Mục đích
default	explore → plan → execute → verify	Cân bằng, đa năng
fast-fix	explore → execute → verify	Sửa bug nhỏ nhanh
implementation	Adaptive planner quyết fanout	Multi-file implementation
review	explore → code-review → security-review → verify	Code review + security audit
research	explore → analyze → write	Nghiên cứu và viết tài liệu

Builtin Agents

analyst  ·  critic  ·  executor  ·  explorer  ·  planner  ·  reviewer
security-reviewer  ·  test-engineer  ·  verifier  ·  writer

---

Runtime Safety

By default, run launches each task as a separate child Pi process. Workers execute independently and stream output to durable state.

Scaffold/dry-run mode (no real workers):

{ "runtime": { "mode": "scaffold" } }

Disable workers globally:

{ "executeWorkers": false }

Worktree mode is opt-in and requires a clean repo:

{
  "action": "run",
  "team": "implementation",
  "goal": "Refactor auth",
  "workspaceMode": "worktree"
}

---

Configuration

Config Paths

Scope	Path
User	~/.pi/agent/extensions/pi-crew/config.json
Project (new)	.crew/config.json
Project (legacy)	.pi/teams/config.json

Quick Config

/team-config                                       # view
/team-config asyncByDefault=true                    # update
/team-config runtime.mode=scaffold                  # scaffold mode
/team-config --unset=asyncByDefault                 # reset
/team-config autonomous.profile=assisted --project  # project scope

Key Settings

Section	Key Settings	Default
Runtime	mode: auto | scaffold | child-process | live-session	auto
Concurrency	limits.maxConcurrentWorkers	workflow-dependent (2–4)
Async	asyncByDefault, runtime.groupJoin	false, smart
Autonomy	profile: manual | suggested | assisted | aggressive	suggested
UI	widgetPlacement, dashboardPlacement, showModel, showTokens	compact widget
Reliability	autoRetry, autoRecover, deadletterThreshold	all opt-in
Observability	prometheus.enabled, otlp.enabled	opt-in

⚠️ Trust boundary: project config cannot override sensitive execution controls (workers, runtime mode, autonomy, agent overrides). Set those in user config only.

📖 Full config reference: docs/configuration.md (coming soon — see docs/usage.md for now)

---

Tool Actions

{ "action": "run", "team": "default", "goal": "..." }       // execute
{ "action": "status", "runId": "team_..." }                   // monitor
{ "action": "cancel", "runId": "team_..." }                   // stop
{ "action": "resume", "runId": "team_..." }                   // continue
{ "action": "recommend", "goal": "..." }                       // get advice
{ "action": "list" }                                            // discover
{ "action": "create", "resource": "agent", ... }              // extend
{ "action": "doctor" }                                          // diagnose

📖 Full actions reference: docs/actions-reference.md

---

Slash Commands

/team-run [--team=X] [--async] [--worktree] <goal>
/team-status <runId>
/team-dashboard
/team-doctor
/team-init [--copy-builtins]
/team-config [key=value]
/team-autonomy [status|on|off|suggested|assisted]

📖 Full commands reference: docs/commands-reference.md

---

Resource Discovery

Agents, teams, and workflows are discovered from three layers:

builtin (package)  <  user (~/.pi/agent/)  <  project (.crew/ or .pi/teams/)

Project resources can add new names but cannot shadow builtin/user resources.

Resource Paths

Type	Builtin	User	Project
Agent	agents/*.md	~/.pi/agent/agents/*.md	.crew/agents/*.md
Team	teams/*.team.md	~/.pi/agent/teams/*.team.md	.crew/teams/*.team.md
Workflow	workflows/*.workflow.md	~/.pi/agent/workflows/*.workflow.md	.crew/workflows/*.workflow.md

Custom Resources with Routing Metadata

---
name: api-reviewer
description: Reviews API changes
triggers: api, endpoint, contract
useWhen: backend API changes, OpenAPI changes
avoidWhen: docs-only edits
cost: cheap
category: backend
---
Your system prompt here.

📖 Full resource formats: docs/resource-formats.md

---

State Layout

<crewRoot>/                          # .crew/ (new) or .pi/teams/ (legacy)
├── state/runs/{runId}/
│   ├── manifest.json                # run metadata
│   ├── tasks.json                   # task graph + status
│   ├── events.jsonl                 # append-only events
│   └── agents/{taskId}/status.json  # per-agent state
├── artifacts/{runId}/
│   ├── goal.md
│   ├── prompts/{taskId}.md
│   ├── results/{taskId}.txt
│   ├── logs/{taskId}.log
│   └── summary.md
├── worktrees/{runId}/{taskId}/
└── imports/{runId}/run-export.json

---

Environment Variables

Variable	Purpose
PI_CREW_EXECUTE_WORKERS=0	Disable child workers (scaffold mode)
PI_TEAMS_EXECUTE_WORKERS=0	Legacy disable flag
PI_TEAMS_MOCK_CHILD_PI=success	Mock child worker for testing
PI_TEAMS_PI_BIN=<path>	Explicit Pi CLI path
PI_TEAMS_HOME=<path>	Override home for tests

---

Development

cd pi-crew
npm install          # dependencies
npm test             # unit + integration tests
npm run typecheck    # tsc --noEmit
npm run ci           # full CI-equivalent check
npm pack --dry-run   # package verification

CI runs on: ubuntu-latest · windows-latest · macos-latest

---

Documentation

Doc	Contents
docs/actions-reference.md	Full tool actions + examples
docs/commands-reference.md	Slash commands + /team-api
docs/resource-formats.md	Agent/team/workflow file formats
docs/usage.md	Usage patterns + config examples
docs/architecture.md	Internal architecture + run flow
docs/runtime-flow.md	Runtime execution details
docs/live-mailbox-runtime.md	Mailbox + live-session runtime
docs/publishing.md	Release & publish process
docs/next-upgrade-roadmap.md	Future upgrade roadmap
schema.json	Config JSON schema

Research docs (not in package): docs/pi-crew-research/ — audits, deep research, distillation notes.

---

Acknowledgements

pi-crew builds on ideas and selected MIT-licensed implementation patterns from pi-subagents and oh-my-claudecode, with conceptual inspiration from oh-my-openagent.