pi-teams 🚀

pi-teams turns your single Pi agent into a coordinated software engineering team. It allows you to spawn multiple "Teammate" agents in separate terminal panes that work autonomously, communicate with each other, and manage a shared task board—all mediated through tmux, Zellij, iTerm2, WezTerm, or Windows Terminal.

🖥️ pi-teams in Action

| iTerm2 | tmux | Zellij | | :---: | :---: | :---: | | | | |

Also works with WezTerm and Windows Terminal (cross-platform support)

🛠 Installation

Open your Pi terminal and type:

pi install npm:pi-teams

🚀 Quick Start

# 1. Start a team (inside tmux, Zellij, or iTerm2)
"Create a team named 'my-team' using 'gpt-4o'"

# 2. Spawn teammates
"Spawn 'security-bot' to scan for vulnerabilities"
"Spawn 'frontend-dev' using 'haiku' for quick iterations"

# 3. Create and assign tasks
"Create a task for security-bot: 'Audit auth endpoints'"

# 4. Review and approve work
"List all tasks and approve any pending plans"

🌟 What can it do?

Core Features

• Spawn Specialists: Create agents like "Security Expert" or "Frontend Pro" to handle sub-tasks in parallel.
• Shared Task Board: Keep everyone on the same page with a persistent list of tasks and their status.
• Agent Messaging: Agents can send direct messages to each other and to you (the Team Lead) to report progress.
• Autonomous Work: Teammates automatically "wake up," read their instructions, and poll their inboxes for new work while idle.
• Beautiful UI: Optimized vertical splits in tmux with clear labels so you always know who is doing what.

Advanced Features

• Predefined Teams: Define team templates in teams.yaml and spawn entire teams with a single command.
• Save Teams as Templates: Convert any runtime team into a reusable template with a single command.
• Isolated OS Windows: Launch teammates in true separate OS windows instead of panes.
• Persistent Window Titles: Windows are automatically titled [team-name]: [agent-name] for easy identification in your window manager.
• Plan Approval Mode: Require teammates to submit their implementation plans for your approval before they touch any code.
• Broadcast Messaging: Send a message to the entire team at once for global coordination and announcements.
• Quality Gate Hooks: Automated shell scripts run when tasks are completed (e.g., to run tests or linting).
• Thinking Level Control: Set per-teammate thinking levels (off, minimal, low, medium, high) to balance speed vs. reasoning depth.

💬 Key Examples

1. Start a Team

You: "Create a team named 'my-app-audit' for reviewing the codebase."

Set a default model for the whole team:

You: "Create a team named 'Research' and use 'gpt-4o' for everyone."

Start a team in "Separate Windows" mode:

You: "Create a team named 'Dev' and open everyone in separate windows." (Supported in iTerm2 and WezTerm only)

2. Spawn Teammate with Custom Settings

You: "Spawn a teammate named 'security-bot' in the current folder. Tell them to scan for hardcoded API keys."

Spawn a specific teammate in a separate window:

You: "Spawn 'researcher' in a separate window."

Move the Team Lead to a separate window:

You: "Open the team lead in its own window." (Requires separate_windows mode enabled or iTerm2/WezTerm)

Use a different model:

You: "Spawn a teammate named 'speed-bot' using 'haiku' to quickly run some benchmarks."

Require plan approval:

You: "Spawn a teammate named 'refactor-bot' and require plan approval before they make any changes."

Customize model and thinking level:

You: "Spawn a teammate named 'architect-bot' using 'gpt-4o' with 'high' thinking level for deep reasoning."

Smart Model Resolution: When you specify a model name without a provider (e.g., gemini-2.5-flash), pi-teams automatically:

• Queries available models from pi --list-models
• Prioritizes OAuth/subscription providers (cheaper/free) over API-key providers:
  • google-gemini-cli (OAuth) is preferred over google (API key)
  • github-copilot, kimi-sub are preferred over their API-key equivalents
• Falls back to API-key providers if OAuth providers aren't available
• Constructs the correct --model provider/model:thinking command

Example: Specifying gemini-2.5-flash will automatically use google-gemini-cli/gemini-2.5-flash if available, saving API costs.

3. Assign Task & Get Approval

You: "Create a task for security-bot: 'Check the .env.example file for sensitive defaults' and set it to in_progress."

Teammates in planning mode will use task_submit_plan. As the lead, review their work:

You: "Review refactor-bot's plan for task 5. If it looks good, approve it. If not, reject it with feedback on the test coverage."

4. Broadcast to Team

You: "Broadcast to the entire team: 'The API endpoint has changed to /v2. Please update your work accordingly.'"

5. Shut Down Team

You: "We're done. Shut down the team and close the panes."

Automatic Cleanup: When you shut down a team, pi-teams automatically cleans up orphaned agent session folders from ~/.pi/agent/teams/ that are older than 1 hour. This prevents accumulation of stale session data over time.

Manual Cleanup: If you need to clean up agent sessions without shutting down a team, or want to use a different age threshold:

You: "Clean up agent session folders older than 24 hours."

🏗️ Predefined Teams

Predefined teams let you define reusable team templates in a teams.yaml file. This is perfect for common workflows where you always want the same set of specialists.

Define Team Templates

Create ~/.pi/teams.yaml (global) or .pi/teams.yaml in your project:

# Full development team
full:
  - scout
  - planner
  - builder
  - reviewer
  - documenter

# Quick plan-build cycle
plan-build:
  - planner
  - builder
  - reviewer

# Research and documentation
research:
  - scout
  - documenter

# Frontend specialists
frontend:
  - planner
  - builder
  - bowser

Define Agent Definitions

Create agent definitions in ~/.pi/agent/agents/ (global) or .pi/agents/ (project-local):

scout.md:

---
name: scout
description: Fast recon and codebase exploration
tools: read,grep,find,ls
---
You are a scout agent. Investigate the codebase quickly and report findings concisely. Do NOT modify any files. Focus on structure, patterns, and key entry points.

builder.md:

---
name: builder
description: Implementation specialist
tools: read,write,edit,bash
model: claude-sonnet-4
thinking: medium
---
You are a builder agent. Implement code following the plan provided. Write clean, tested code.

Agent Definition Fields:

• name (required): The agent's name
• description (required): What the agent does
• tools (optional): Comma or space-separated list of allowed tools
• model (optional): Model to use (e.g., claude-sonnet-4, gpt-4o)
• thinking (optional): Thinking level (off, minimal, low, medium, high)

Use Predefined Teams

List available team templates:

You: "List all predefined teams I can use."

List available agent definitions:

You: "Show me all predefined agents."

Create a team from a template:

You: "Create a team named 'my-project' from the 'plan-build' predefined team in the current directory."

This single command:

1. Creates the team
2. Spawns all agents defined in the template
3. Each agent gets its predefined prompt, tools, model, and thinking settings

With options:

You: "Create a team named 'big-team' from 'full' predefined team using 'gpt-4o' as default model and separate windows."

💾 Save Teams as Templates

Sometimes you create a team with custom prompts and settings that you'd like to reuse later. Instead of manually creating teams.yaml and agent definition files, you can save any runtime team as a template.

The Workflow

CREATE → USE → SAVE → REUSE

1. Create a team with custom teammates and prompts
2. Use the team for your task
3. Save the team as a reusable template
4. Reuse the template later (even on different projects)

List Runtime Teams

See which teams you have that can be saved:

You: "List all runtime teams."

Save a Team as a Template

You: "Save team 'my-modularization-team' as template 'code-modularization'"

This creates:

• Agent definition files in ~/.pi/agent/agents/ for each teammate
• Updates ~/.pi/teams.yaml with the new template

Save to Project-Local Scope

To save a template that's specific to the current project:

You: "Save team 'my-frontend-team' as template 'frontend-sprint' with scope 'project'"

This creates files in .pi/agents/ and .pi/teams.yaml in the current project directory.

Reuse Your Template

Once saved, use it just like any predefined team:

You: "Create a team named 'auth-refactor' from the 'code-modularization' template in the current directory"

📚 Learn More

• Full Usage Guide - Detailed examples, hook system, best practices, and troubleshooting
• Tool Reference - Complete documentation of all tools and parameters

🪟 Terminal Requirements

To show multiple agents on one screen, pi-teams requires a way to manage terminal panes. It supports tmux, Zellij, iTerm2, WezTerm, and Windows Terminal.

Option 1: tmux (Recommended)

Install tmux:

• macOS: brew install tmux
• Linux: sudo apt install tmux

How to run:

tmux  # Start tmux session
pi   # Start pi inside tmux

Option 2: Zellij

Simply start pi inside a Zellij session. pi-teams will detect it via the ZELLIJ environment variable and use zellij run to spawn teammates in new panes.

Option 3: iTerm2 (macOS)

If you are using iTerm2 on macOS and are not inside tmux or Zellij, pi-teams can manage your team in two ways:

1. Panes (Default): Automatically split your current window into an optimized layout.
2. Windows: Create true separate OS windows for each agent.

It will name the panes or windows with the teammate's agent name for easy identification.

Option 4: WezTerm (macOS, Linux, Windows)

WezTerm is a GPU-accelerated, cross-platform terminal emulator written in Rust. Like iTerm2, it supports both Panes and Separate OS Windows.

Install WezTerm:

• macOS: brew install --cask wezterm
• Linux: See wezterm.org/installation
• Windows: Download from wezterm.org

How to run:

wezterm  # Start WezTerm
pi       # Start pi inside WezTerm

Option 5: Windows Terminal (Windows)

Windows Terminal is the modern, feature-rich terminal emulator for Windows 10/11. It supports both Panes and Separate OS Windows.

Requirements:

• Windows 10 (version 19041 or later) or Windows 11
• Windows Terminal installed (available from Microsoft Store or winget)
• PowerShell 5.1 or later (pwsh.exe)

Install Windows Terminal:

• Microsoft Store: Search for "Windows Terminal" and install
• winget: winget install Microsoft.WindowsTerminal
• Scoop: scoop install windows-terminal

Install PowerShell Core (optional but recommended):

• winget: winget install Microsoft.PowerShell
• Scoop: scoop install powershell

How to run:

# Open Windows Terminal and start pi
wt
pi

Or start pi directly from Windows Terminal with new window:

wt -- pwsh -c "pi"

Note: On Windows, pi-teams uses PowerShell for command execution. Make sure pi is in your PATH. If you installed pi via npm and Node.js, verify both are accessible from PowerShell.

📜 Credits & Attribution

This project is a port of the excellent claude-code-teams-mcp by cs50victor.

We have adapted the original MCP coordination protocol to work natively as a Pi Package, adding features like auto-starting teammates, balanced vertical UI layouts, automatic inbox polling, plan approval mode, broadcast messaging, and quality gate hooks.

📄 License

MIT