# Pi Team

> 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

- Skill: `changhochien/pi-team` (Agent Skill)
- Install (CLI): `npx skillmds@latest add changhochien/pi-team`
- Raw SKILL.md: https://api.skillmd.com/api/skills/changhochien/pi-team/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: changhochien (https://skillmd.com/u/changhochien)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/changhochien/pi-team

---


# pi-team Skill

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

## Prerequisites

```bash
# 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:

```bash
pi-team --help
```

## Usage

### spawn

Spawn N agents with specified providers:

```bash
/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:

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

### aggregate

Collect and format results:

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

### shutdown

Stop all workers gracefully:

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

### log

View worker logs:

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

### attach

Attach to a worker tmux session (interactive):

```bash
/skill:pi-team attach worker-1
```

### send

Send a message to a running worker:

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

### task

Assign a new task to a worker:

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

## Workflow Examples

### Example 1: Feature Implementation

```bash
# 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

```bash
# 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

```bash
# 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:

```json
{
  "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":**
```bash
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:**
```bash
pi-team shutdown --force
```

**Attach hanging:**
- Press `Ctrl+B` then `D` to detach from tmux