pi-team-agents Guide: Coordinate AI Agent Teams in Pi CLI with Mailbox Messaging

pi-team-agents Guide: Coordinate AI Agent Teams in Pi CLI with Mailbox Messaging

pi-team-agents is a Pi extension that spawns teams of AI agents that collaborate on complex tasks. Unlike other extensions where a central orchestrator routes every message, pi-team-agents agents communicate directly via mailboxes — event-driven messaging with zero polling and instant relay. The system includes 6 built-in agents (explore, planner, coder, reviewer, general-purpose, verification), a shared task board, persistent shared memory, and two workflows: team_dispatch (parallel batch) and team_create+team_spawn (sequential pipeline). (Source: github.com/Jabbslad/pi-team-agents)

The Real Problem

Complex software tasks need multiple perspectives. A code change needs exploration, planning, implementation, review, and verification. In a single-agent Pi session, each perspective competes for context window space. The agent's exploration mode fills the context with file listings, then planning mode suffers from pollution. pi-team-agents solves this by giving each perspective its own in-process session with an independent context window — and enabling direct agent-to-agent communication so they don't bother the parent for every coordination.

[ STAT ] Multi-agent in-process sessions reduce task completion time by 60% vs sequential single-agent sessions. — pi-team-agents architecture docs, June 2026

What This Workflow Actually Does

pi-team-agents spawns agents as in-process sessions with independent context windows, mailbox-based messaging, and a shared task board.

[TOOL: team_dispatch] Spawn N agents in parallel, wait for all results. Zero coordination overhead.

[TOOL: team_create + team_spawn] Sequential pipeline control. Explore → Plan → Code → Review → Verify.

[TOOL: Shared Memory] Key-value store with secret scanning. Agents persist knowledge across the team.

Who This Is Built For

For Pi CLI developers refactoring complex codebases: explore architecture, design approach, implement changes, review, and verify — all in parallel with context isolation.

For senior engineers doing code review: spawn a reviewer and a verifier simultaneously. One examines quality, the other tries to break it.

For teams adopting Pi for structured development: the sequential pipeline enforces consistent process without manual management.

How It Runs Step by Step

1. Parallel Dispatch: team_dispatch spawns N agents (explore, plan, review). All start simultaneously with independent contexts.

2. Mailbox Communication: Agents message each other directly via event-driven mailboxes. No parent routing needed.

3. Task Board: Shared board tracks work items with status, ownership, and dependencies.

4. Shared Memory: Agents persist and retrieve knowledge via team_memory_write and team_memory_read.

5. Sequential Pipeline: team_create + team_spawn for dependent stages — each receives the prior agent's output.

Setup and Tools

pi-team-agents: pi install git:github.com/Jabbslad/pi-team-agents. 6 built-in agents, in-process sessions. Gotcha: agents are in-process, not child processes. A crash may affect the parent.

Custom agents: Define in .pi/agents/*.md with YAML frontmatter. Fields: name, description, tools, model, color, maxTurns.

The Numbers

▸ Task completion: 4-6 hours sequential → 1-2 hours parallel teams ▸ Context interference: 35% token waste → 0% with isolated contexts ▸ Review cycle: 2-3 hours → 20-30 minutes parallel ▸ Communication overhead: parent-mediated → zero-overhead mailbox relay ▸ Time to first ROI: first team_dispatch completes research+review+planning in 10 minutes (Source: pi-team-agents docs, June 2026)

What It Cannot Do

1. In-process agents share Pi's event loop. CPU-intensive tasks may block the main session.
2. No async/background execution. Closing Pi kills all agents.
3. Secret scanning may block legitimate storage of config values that resemble secrets.

Start in 10 Minutes

1. (2 min) Install pi-team-agents: pi install git:github.com/Jabbslad/pi-team-agents
2. (3 min) Run team_dispatch: create a team and dispatch an explore + planner agent
3. (5 min) Check the task board with /tasks and agent status with /team

Frequently Asked Questions

Q: Are agents in-process or child processes? A: In-process sessions within the same Pi process. This means faster startup and lower memory than child processes, but an agent crash may affect the parent.

Q: Can agents run in the background? A: No. All agents run within the active Pi session. Background/async execution is not supported in the current version.

Q: How do I define custom agents? A: Create .md files in .pi/agents/ (project) or ~/.pi/agent/agents/ (global) with YAML frontmatter including name, description, tools, and model.