pi-team-agents: Multi-Agent Team Coordination with In-Process Sessions

pi-team-agents is a Pi extension by Jabbslad that spawns teams of AI agents — explorers, planners, coders, reviewers, verifiers — that collaborate on tasks using in-process sessions with mailbox-based messaging, a shared task board, and persistent shared memory. Agents run as in-process Pi sessions with their own context windows, avoiding the overhead of separate child processes. The agentic reasoning step occurs through the shared memory system — agents can persist and exchange knowledge across the team without the parent session coordinating every interaction. This is agentic because agents communicate directly via mailboxes rather than routing all communication through a central orchestrator. Two workflows are supported: team_dispatch for parallel batch execution (spawn N agents, wait for all results) and team_create + team_spawn for sequential pipelines (one agent's output feeds the next). pi-team-agents includes 6 built-in agents (explore, planner, coder, reviewer, general-purpose, verification) with customizable frontmatter-based configuration.

BUSINESS PROBLEM

Complex software tasks require multiple cognitive perspectives. A code change needs exploration (where are the relevant files?), planning (what's the best approach?), implementation (write the code), review (does it have bugs?), and verification (can tests break it?). In a single-agent Pi session, each perspective competes for context window space. The agent's 'exploration mode' fills the window with file listings, then it must 'switch' to planning mode but the file listings are still there. According to pi-team-agents' architecture documentation, in-process multi-agent sessions with isolated contexts reduce task completion time by 60% compared to sequential single-agent sessions for complex multi-perspective tasks. The key insight: separate context windows per cognitive perspective eliminate the interference that plagues single-agent sessions.

WHO BENEFITS

Pi CLI developers refactoring complex codebases: you need to explore the architecture, design the approach, implement changes, review them, and verify nothing broke. pi-team-agents runs all perspectives in parallel with isolated contexts. Senior engineers doing code review: you can spawn a reviewer agent and a verification agent simultaneously — one examines code quality, the other tries to break it. The shared memory lets them share findings without parent coordination. Teams adopting Pi for structured development workflows: pi-team-agents' sequential pipeline (explore → plan → implement → verify) enforces a consistent process across all team members without manual process management.

HOW IT WORKS

1. Team Creation: The user calls team_create to instantiate a team. The current Pi session becomes the team lead. Agents are discovered from .pi/agents/ (project), ~/.pi/agent/agents/ (global), or built-in definitions. Output: team object with status tracking.
2. Parallel Dispatch (team_dispatch): The user spawns N agents in parallel — e.g., an explorer to map files, a planner to design approach, and a reviewer to check existing code. All agents start simultaneously with independent context windows. The parent waits for all results to arrive atomically.
3. Mailbox-Based Communication: Agents communicate via event-driven mailboxes. An explorer can send findings to the planner without the parent routing the message. Messages are instant relay — no polling, no parent intervention.
4. Task Board Management: The shared task board tracks work items with status, ownership, and dependencies. Agents create, update, and complete tasks independently. The parent can inspect the board at any time via task_list.
5. Shared Memory: Agents persist knowledge via team_memory_write and retrieve it via team_memory_read. A planner stores architectural decisions. A coder retrieves them during implementation. Shared memory supports key-value storage with secret scanning (blocks API keys, tokens).
6. Sequential Pipeline (team_create + team_spawn): For dependent tasks, the user spawns agents sequentially — explorer to gather context, planner to design, coder to implement, reviewer to audit, verifier to try to break it. Each agent receives the prior agent's output.
7. Live Monitoring: The TUI footer shows which agents are busy (●) or idle (○). The user can inspect any agent's output, interrupt a stuck agent, or send steering messages via send_message.

TOOL INTEGRATION

pi-team-agents (Jabbslad, MIT): Multi-agent team coordination for Pi CLI. Install: pi install git:github.com/Jabbslad/pi-team-agents. 6 built-in agents with frontmatter configuration. GitHub: github.com/Jabbslad/pi-team-agents. Gotcha: pi-team-agents runs agents as in-process sessions, not child processes. If an agent crashes, it may affect the parent Pi process.

Pi CLI (@badlogic/pi-coding-agent, v0.69+): Host runtime. The extension uses Pi's SDK for in-process agent sessions. Gotcha: In-process agents share Pi's event loop. CPU-intensive agent tasks can block the main session's responsiveness.

Custom Agent Definitions (Markdown): Users define custom agents in .pi/agents/*.md with YAML frontmatter. Fields: name, description, tools, disallowedTools, model, color, maxTurns, initialPrompt, background, criticalSystemReminder. Gotcha: Custom agents defined in .pi/agents/ are project-specific. To share across projects, use ~/.pi/agent/agents/ instead.

ROI METRICS

1. Multi-perspective task completion: 4-6 hours sequential → 1-2 hours with parallel agent teams (Source: pi-team-agents architecture docs, June 2026)
2. Context interference in single-agent: 35% token waste from conflicting context → 0% with isolated per-agent context windows
3. Review + verification cycle: 2-3 hours manual sequential → 20-30 minutes parallel dispatch
4. Communication overhead: parent-mediated messaging → zero-overhead mailbox-based agent-to-agent relay
5. Time to first ROI: first team_dispatch call completes research + review + planning in under 10 minutes

CAVEATS

1. In-process agents share Pi's memory and event loop. Running 5+ agents simultaneously on CPU-intensive tasks (e.g., large file reads) can degrade the main session's responsiveness.
2. The shared memory system blocks writes containing API keys, tokens, and other secrets. While this is a security feature, it may also block legitimate storage of configuration values that resemble secrets.
3. pi-team-agents does not support async/background execution in its current version. All agents run within the active session. Closing Pi kills all running agents.
4. Custom agent frontmatter requires YAML knowledge. The format is not validated at load time — a typo in tools: causes the agent to silently fall back to default tool access.