pi-crew Guide: Deploy Durable Multi-Agent Teams in Pi CLI with Worktree Isolation

pi-crew Guide: Deploy Durable Multi-Agent Teams in Pi CLI with Worktree Isolation

pi-crew is a Pi extension that brings production-grade multi-agent orchestration to the Pi coding agent. It provides 10 built-in agents (analyst, critic, executor, explorer, planner, reviewer, security-reviewer, test-engineer, verifier, writer), 6 built-in teams (default, fast-fix, implementation, review, research, parallel-research), and 4 runtime modes (auto, child-process, scaffold, live-session). The killer features are durable disk-persisted state (workflows survive Pi session crashes and reloads) and git worktree isolation (parallel agents edit independently without conflicts). (Source: github.com/baphuongna/pi-crew)

The Real Problem

Multi-agent Pi workflows lack durability. A code review spawning 5 agents — security, lint, architecture, tests, docs — cannot survive a Pi session crash. If any agent fails mid-task, the entire workflow restarts from scratch. According to pi-crew's architecture documentation, state loss is the #1 reported issue in the Pi extension community. Additionally, parallel agents editing the same files create race conditions. pi-crew solves both: durable persistence ensures crash recovery, and worktree isolation ensures conflict-free parallel execution.

[ STAT ] State loss is the #1 reported issue in the Pi multi-agent extension community. — pi-crew architecture docs, June 2026

What This Workflow Actually Does

pi-crew orchestrates autonomous multi-agent workflows with durable state, concurrent execution, and worktree isolation. The adaptive planning workflow lets a planner agent dynamically decide the subagent fanout based on task complexity.

[TOOL: team] Single tool handling routing, planning, execution, review, and cleanup. Configurable via frontmatter files.

[TOOL: Worktree Isolation] Git worktrees per task for safe parallel edits. Each agent modifies files in its own directory without conflicts.

[TOOL: Durable State] Manifests, tasks, events, artifacts all persisted to disk. Workflows survive Pi session crashes and reloads.

Who This Is Built For

For Pi CLI users running complex code review workflows: 5 agents analyzing security, style, architecture, tests, and docs in parallel without conflicts. pi-crew's worktree isolation makes this safe.

For teams running Pi in CI/CD: crash recovery ensures your pipeline agents complete even across session boundaries.

For engineers needing production observability: pi-crew's Prometheus/OTLP exporters provide metrics, heartbeat monitoring, and deadletter queues.

How It Runs Step by Step

1. Team Selection: User selects a team (default, fast-fix, implementation, review, research) or defines a custom one.

2. Adaptive Planning: The planner agent analyzes the task and decides optimal subagent count, roles, and concurrency.

3. Parallel Spawn: Child Pi processes spawn for each task. Tasks run concurrently with configurable limits.

4. State Persistence: Every task's state writes to disk. If the session crashes, the run survives.

5. Quality Gates: The verifier evaluates outputs. Tasks without submit_result get needs_attention status.

6. Async Completion: Background runs survive session switches. Notifications arrive when tasks complete.

Setup and Tools

pi-crew: pi install npm:pi-crew. 10 agents, 6 teams, 4 runtime modes. Gotcha: async background mode requires Pi v0.70+.

Worktree mode: Opt-in per team config. Each worktree uses ~1x repo disk space.

The Numbers

▸ Crash recovery: 100% manual restart → 0-second resume with durable persistence ▸ Parallel review: 1 sequential agent → 5 parallel agents in worktrees ▸ Code conflicts: 30-40% shared-directory → 0% with worktree isolation ▸ Observability setup: 2-3 weeks custom → 10 minutes Prometheus exporter ▸ Time to first ROI: first multi-agent review completes 4x faster (Source: pi-crew docs, June 2026)

What It Cannot Do

1. Each agent is a full Pi process. 10 agents can consume 2-5GB RAM.
2. Worktrees use significant disk. For 1GB repos, 5 agents = 6GB total.
3. The adaptive planner may under-fanout or over-fanout. Tuning requires experimentation.

Start in 10 Minutes

1. (2 min) Install pi-crew: pi install npm:pi-crew
2. (5 min) Run the default team: /team-run "review the current diff" --team=review
3. (3 min) Check the dashboard: /team-dashboard shows all agents and their status

Frequently Asked Questions

Q: How is pi-crew different from pi-taskflow? A: pi-crew is heavier — durable state, worktree isolation, async runs, Prometheus monitoring. pi-taskflow is lighter — zero dependencies, declarative JSON DSL, cross-session resume. Use pi-crew for production teams, pi-taskflow for lightweight pipelines. (Source: pi-crew and pi-taskflow docs, June 2026)

Q: Can pi-crew agents run asynchronously? A: Yes, with pi-crew's async/background mode. Runs are detached from the session and survive session switches. Results are delivered via push notifications.

Q: What's the security model for pi-crew? A: Agents use real Pi child processes with their own tool access. Read-only agents cannot edit or write files. The security-reviewer agent specifically audits for vulnerabilities.