pi-team

name	pi-team
description	tmux-based multi-agent orchestration using pi-team CLI. Spawn multiple AI agents (PI, Claude, Codex, Gemini) in parallel tmux sessions. USE FOR: parallel implementation, multi-provider coordination, large-scale tasks, distributed work. Commands: /skill:pi-team spawn N:provider "task", /skill:pi-team status, /skill:pi-team aggregate, /skill:pi-team shutdown
level	4

pi-team Skill

tmux-based multi-agent orchestration using the pi-team CLI tool.

Prerequisites

# Install pi-team
npm install -g @oh-my-pi/pi-team

# Ensure tmux is installed
brew install tmux  # macOS
sudo apt install tmux  # Linux

Installation Check

Run this to verify pi-team is installed:

pi-team --help

Usage

spawn

Spawn N agents with specified providers:

/skill:pi-team spawn 3:pi "implement user authentication"
/skill:pi-team spawn 2:pi 1:codex "build the full application"
/skill:pi-team spawn 5 --task "fix all TypeScript errors"

Multi-provider syntax:

• 3:pi - 3 PI agents
• 2:pi 1:codex - 2 PI agents + 1 Codex agent
• 1:pi 1:claude 1:gemini - Mixed providers

status

Monitor worker progress:

/skill:pi-team status
/skill:pi-team status --watch

aggregate

Collect and format results:

/skill:pi-team aggregate
/skill:pi-team aggregate --format markdown > results.md

shutdown

Stop all workers gracefully:

/skill:pi-team shutdown
/skill:pi-team shutdown --force

log

View worker logs:

/skill:pi-team log worker-1
/skill:pi-team log --all

attach

Attach to a worker tmux session (interactive):

/skill:pi-team attach worker-1

send

Send a message to a running worker:

/skill:pi-team send worker-1 "Check the auth module for security issues"

task

Assign a new task to a worker:

/skill:pi-team task worker-1 "Add input validation"

Workflow Examples

Example 1: Feature Implementation

# Initialize team
pi-team init "feature-auth"

# Spawn workers for different parts
pi-team spawn 2:pi --task "implement user registration endpoint (POST /auth/register)"
pi-team spawn 1:pi --task "implement user login endpoint (POST /auth/login)"
pi-team spawn 1:codex --task "add JWT token generation and validation"

# Monitor progress
pi-team status --watch

# When done, aggregate results
pi-team aggregate > auth-implementation.md

# Review and cleanup
pi-team shutdown

Example 2: Large-Scale Refactoring

# Initialize
pi-team init "refactor-api"

# Decompose work
pi-team spawn 3:pi --file modules-to-refactor.txt

# Monitor
pi-team status --watch

# Aggregate
pi-team aggregate --include-logs > refactor-results.md

# Review files, run tests, merge

Example 3: Security Audit

# Multi-provider security review
pi-team spawn 1:pi --task "audit authentication module for vulnerabilities"
pi-team spawn 1:codex --task "review API endpoints for injection risks"
pi-team spawn 1:gemini --task "check data handling for PII compliance"

# Aggregate findings
pi-team aggregate > security-audit.md

# Review and address issues

State Files

pi-team creates state in .pi-team/:

.pi-team/
├── session.json           # Session metadata
├── worker-1/
│   ├── config.json        # Worker config
│   └── output.log         # Worker output
├── worker-2/
│   └── ...
└── worker-3/
    └── ...

Configuration

Create ~/.pi-team/config.json to customize:

{
  "providers": {
    "pi": {
      "command": "pi",
      "args": ["--no-stream"]
    },
    "claude": {
      "command": "claude",
      "args": ["--print", "--model", "sonnet"]
    }
  },
  "defaults": {
    "provider": "pi",
    "max_concurrent": 8
  }
}

Tips

1. Match providers to tasks:

   • PI/Claude: Complex reasoning, architecture
   • Codex: Code review, repetitive patterns
   • Gemini: UI/UX design, documentation

2. Task decomposition:

   • Make tasks independent where possible
   • Each worker should have clear boundaries
   • Document dependencies between workers

3. Progress monitoring:

   • Use status --watch for real-time updates
   • Check individual logs with log <worker-id>
   • Attach to workers with attach <worker-id>

4. Result aggregation:

   • Always run aggregate before shutdown
   • Use --include-logs for debugging
   • Review results before merging

Troubleshooting

"tmux not found":

brew install tmux  # macOS
sudo apt install tmux  # Linux

"Provider not found":

• Check provider name is correct (pi, claude, codex, gemini)
• Ensure the CLI is installed and in PATH

Workers stuck:

pi-team shutdown --force

Attach hanging:

• Press Ctrl+B then D to detach from tmux