pi-crew

Multi-agent team orchestration for Pi.

pi-crew is a Pi extension that adds one team tool for coordinating autonomous agent workflows — research, implementation, review, testing, and cleanup. Each task runs as a real child Pi process, with durable on-disk state, parallel execution, and opt-in git-worktree isolation. Runs can be monitored, steered, resumed, scheduled, and exported.

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

⚠️ IMPORTANT — Read before using

pi-crew was developed almost entirely by AI, for the author's own workflow. It is not a hardened, audited product:

• AI-generated code, limited human review. Every change ships after static review + runtime tests, but nothing is independently audited.
• It acts on your machine. It spawns processes, runs shell commands, and writes files — including project-defined .dwf.ts scripts, which carry the same trust as any node script.js you downloaded.
• Built for one workflow (the author's). It may not fit yours — that's fine.

If that's too risky, don't use it — no hard feelings. If you still want it: fork it, read the parts you'll touch, and adapt it to your setup. Details: trust model · security issues · Known limitations.

Features

• One team tool, 55 actions — run, monitor, steer, schedule, and manage agents/teams/workflows (actions reference).
• Real child Pi workers — each task spawns an isolated pi process; runtime.mode: "scaffold" gives a dry-run with prompts only.
• Built-in teams & adaptive planning — 6 teams and 11 workflows ship in the box; the default and implementation workflows let a planner agent pick the smallest effective crew.
• Parallel execution + worktree isolation — tasks in the same phase run concurrently; workspaceMode: "worktree" gives each task its own git worktree for safe parallel edits.
• Durable runs — manifest, tasks, events, and artifacts persist under .crew/; resume, retry, or steer in-flight tasks; export/import run bundles. .crew/knowledge.md injects durable project learnings into every worker prompt.
• Async background runs — async: true detaches a run so it survives session switches, with completion notification.
• Dynamic workflows — author orchestration as a .dwf.ts script with real JS loops/branching, typed ctx, phases, and token budgets (docs).
• Autonomous goal loops — action: "goal" runs worker → LLM judge → feedback turns until the goal is achieved or budget/turn limits hit (docs).
• Inter-pi broker — concurrent Pi sessions exchange messages and steering over a unix socket; on by default (Linux/macOS), three kill switches.
• Observability & UI — task list above the editor, agent dock, inline transcript panel, dashboard; per-run resource sampler + auto-generated performance report and cost breakdown.

Install

pi install npm:pi-crew

The npm: prefix is required — without it, pi install treats the argument as a local path. Requires Node ≥ 22.

Local development (from a clone):

pi install .

Uninstall

pi uninstall npm:pi-crew removes the package, but pi has no uninstall hook — pi-crew-created state is left behind. Reverse it explicitly:

team action=cleanup dryRun=true            # preview, no writes
team action=cleanup force=true             # remove project guidance block + .crew/
team action=cleanup scope=user force=true  # + user-level state and global config
pi uninstall npm:pi-crew                   # finally, the package itself

Quick start

/team-init
/team-run Investigate failing tests and propose a fix

Or via tool calls (all examples verified against the action schema):

{ "action": "run", "team": "default", "goal": "Investigate failing tests and propose a fix" }
{ "action": "status", "runId": "team_..." }
{ "action": "recommend", "goal": "Refactor auth flow and add tests" }
{ "action": "run", "team": "implementation", "goal": "Refactor auth", "async": true, "workspaceMode": "worktree" }

action: "recommend" picks a team/workflow when you're unsure which fits. Slash commands (/team-status, /team-dashboard, /team-config, …) cover ops and debugging — full list.

Built-in teams

Team	Workflow shape	Use for
default	adaptive: assess → parallel tasks → verify	general-purpose work
fast-fix	explore → execute → verify	small bug fixes
implementation	adaptive planner decides fanout	multi-file features/refactors
review	explore → code-review → security-review → verify	code + security review
research	explore → analyze → write	investigation and documentation
parallel-research	parallel shards → synthesize → write	multi-source audits

18 built-in agents ship in agents/ (explorer, planner, executor, critic, reviewer, verifier, test-engineer, writer, analyst, oracle, librarian, …). Resources are discovered in three layers — builtin package < user (~/.pi/agent/) < project (.crew/) — and project resources cannot shadow builtin ones. Formats: docs/resource-formats.md.

Configuration

Config files (first found wins per scope):

Scope	Path
User	~/.pi/agent/pi-crew.json
User (legacy, still read)	~/.pi/agent/extensions/pi-crew/config.json
Project	.crew/config.json (legacy layout: .pi/teams/config.json; alt: .pi/pi-crew.json)

Most-used keys (full set: docs/usage.md · schema.json):

Key	What it does
runtime.mode 🔒	auto | scaffold | child-process | live-session — how workers execute
executeWorkers 🔒	false = dry-run planning only, no child processes
asyncByDefault 🔒	detach every run by default (survives session switches)
limits.maxConcurrentWorkers	hard cap on parallel workers
runtime.maxTurns	per-task turn ceiling
runtime.requirePlanApproval	pause at the plan→execute boundary for approval
worktree.linkNodeModules	symlink node_modules into task worktrees
agents.overrides 🔒	per-agent model / skills / tools override
reliability.autoRetry	auto-retry failed tasks
broker.enabled	inter-session message bus; default true (PI_CREW_BROKER=0 always wins; auto-off on native Windows)
notifications.webhook 🔒	opt-in outbound webhook on run completion — one POST per terminal run, quiet-hours-aware, SSRF-guarded (see below)

🔒 = sensitive: settable in user config only — project config silently drops these keys with a warning, so untrusted repos can't escalate privileges. Environment variables (PI_CREW_BROKER, PI_CREW_USE_BUNDLE, …) are listed in src/config/env-vars.ts.

Webhook notifications (US-030)

Disabled by default — no URL configured means zero network calls. When a run reaches a terminal status (completed / failed / cancelled), and it is outside notifications.quietHours, pi-crew POSTs one JSON document to your URL (5 s timeout, exactly one retry on 5xx/network error, failures never affect the run):

"notifications": {
  "quietHours": "22:00-07:00",
  "webhook": {
    "url": "https://hooks.example.com/pi-crew",
    "enabled": true,
    "secret": "shared-secret",
    "allowLocalhost": false
  }
}

Payload (PII-safe — no transcripts or events, goal is first-line only): { "event": "run.terminal", "runId": …, "status": …, "team": …, "goal": …, "durationMs": …, "cost": …, "tokens": …, "at": "<ISO>" }. With secret set, every request carries x-pi-crew-signature: sha256=<hmac-sha256(raw body, secret)>. Non-http(s) URLs and loopback/link-local targets (localhost, 127.0.0.0/8, [::1], fe80::/10, 169.254.0.0/16) are refused unless you set allowLocalhost: true explicitly. The whole webhook block is 🔒 — user config only, so an untrusted repo cannot point your runs at an attacker URL.

Where things live

Doc	Contents
docs/README.md	index of all docs (living + archive)
docs/usage.md	usage patterns + config examples
docs/actions-reference.md	all 55 team actions with examples
docs/commands-reference.md	slash commands + /team-api
docs/architecture.md	internal architecture + run flow
docs/troubleshooting.md	common errors, recovery, error codes
docs/trust-model.md	trust boundaries + accepted risks
docs/dynamic-workflows.md	.dwf.ts runtime + its security model
docs/resource-formats.md	agent/team/workflow file formats
docs/publishing.md	release & publish process

Also: schema.json (machine-readable config) · CHANGELOG.md (version history) · skills/ (bundled skills) · NOTICE.md (attributions).

Known limitations

• .dwf.ts scripts are not sandboxed. They run in plain module scope with full require/process access (postinstall-equivalent trust). Only run scripts you have reviewed. See the security model.
• Workers run with your privileges; verification is best-effort. Guards (read-only defaults for unknown roles, path allowlists, sensitive-key sanitizing) raise the bar, but they are not a boundary against a malicious worker in the same process. See docs/trust-model.md.
• AI-developed, single maintainer. Every change ships after static review
  • runtime tests, but there is no independent human audit. Found a bug or a sharp edge? Open an issue.

Development

npm install
npm test                # unit + integration suites
npm run test:critical   # fast broker/UI subset (~20s)
npm run typecheck       # tsc --noEmit + strip-types import check
npm run lint            # biome (linters only)
npm run format:check    # biome format
npm run ci              # full gate: checks, typecheck, lint, bundle, tests, pack
npm run build:bundle    # rebuild dist/index.mjs

Running Pi sessions load the pre-built dist/index.mjs bundle — rebuild (npm run build:bundle, or npm run watch:bundle while editing) and start a new Pi session to pick up source changes.

License

MIT — see LICENSE.