agent-teams

What this skill does

# Agent Teams

Coordinate multiple Claude Code instances as a team with shared task lists, inter-agent messaging, and independent context windows. Fundamentally different from subagents (Task tool): teammates communicate directly with each other, not just back to the caller.

## When to Use Agent Teams vs Subagents

```
Does the work require inter-agent communication?
├── No → Use subagents (Task tool)
│   ├── Focused tasks where only the result matters
│   ├── Research/verification that reports back
│   └── Lower token cost (results summarized to main context)
└── Yes → Use Agent Teams
    ├── Teammates need to share findings mid-task
    ├── Adversarial debate / competing hypotheses
    ├── Self-organizing work from shared task list
    └── Complex coordination across 3+ parallel workers

How many parallel workers?
├── 1-3 independent tasks → Subagents (less overhead)
├── 3-5 coordinating workers → Agent Teams
└── 5+ workers → Agent Teams with delegate mode
```

**Best use cases:**
- Research + review from multiple perspectives simultaneously
- Multi-module features where teammates own different files
- Debugging with competing hypotheses (adversarial investigation)
- Cross-layer coordination (frontend, backend, tests)

**Avoid when:**
- Sequential tasks with many dependencies
- Same-file edits (causes overwrites)
- Simple focused work (coordination overhead not worth it)
- Routine tasks (single session more cost-effective)

## Environment Setup

Enable Agent Teams (experimental, disabled by default):

```json
// settings.json (user or project level)
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

Or set in shell: `export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`

## Tool Architecture

Agent Teams use four distinct tools (not a single "TeammateTool"):

| Tool | Purpose |
|------|---------|
| **TeamCreate** | Creates team config + task directory. Caller becomes lead |
| **SendMessage** | All inter-agent communication (5 message types below) |
| **TeamDelete** | Removes team resources after shutdown (cleanup) |
| **Task** (extended) | Spawns teammates when `name` + `team_name` params present |

### SendMessage Types

| Type | Parameters | Description |
|------|-----------|-------------|
| `message` | `recipient`, `content`, `summary` | Direct message to one teammate |
| `broadcast` | `content`, `summary` | Message to all teammates (expensive — N deliveries) |
| `shutdown_request` | `recipient`, `content` | Request teammate termination (lead only) |
| `shutdown_response` | `request_id`, `approve`, `content` | Accept/reject shutdown (teammate only) |
| `plan_approval_response` | `request_id`, `approve`, `recipient`, `content` | Approve/reject plan (lead only) |

**Critical:** Plain text output is NOT visible to teammates. Agents MUST use SendMessage for all inter-agent communication.

**Usage notes:**
- Prefer `message` over `broadcast` — broadcast creates N messages for N teammates
- Messages delivered automatically to recipient inboxes (no polling)
- Idle notifications sent automatically when teammates finish
- Only the lead should run TeamDelete — teammate context may not resolve correctly

## Spawning Teammates

**Method 1: Natural language** — Tell Claude to create a team and describe structure:

```
Create an agent team to review this PR. Spawn three reviewers:
- One focused on security
- One checking performance
- One validating test coverage
```

**Method 2: Task tool with team parameters:**

```
Task({
  team_name: "my-team",
  name: "worker-1",
  subagent_type: "general-purpose",
  prompt: "Review src/auth/ for security vulnerabilities...",
  model: "sonnet",
  run_in_background: true
})
```

**Teammate receives on spawn:**
- Same project context as regular session (CLAUDE.md, MCP servers, skills)
- The spawn prompt from the lead
- Does NOT inherit lead's conversation history

**Built-in agent types for teammates:**

| Type | Capabilities |
|------|-------------|
| `general-purpose` | All tools (Edit, Write, Bash, Task, etc.) |
| `Explore` | Read-only — codebase search and analysis |
| `Plan` | Read-only — architectural design |
| `Bash` | System commands only |

**Model selection:** Use Sonnet for most teammates (cost-effective). Reserve Opus for leads or complex reasoning tasks. Specify via `model` parameter or natural language ("Use Sonnet for each teammate").

## Spawn Backends

Controls how teammates display. Set via `teammateMode` in settings.json or `--teammate-mode` CLI flag.

| Mode | Setting | Requirements | Behavior |
|------|---------|-------------|----------|
| Auto (default) | `"auto"` | None | Split panes if in tmux, else in-process |
| In-process | `"in-process"` | None | All in main terminal. Shift+Up/Down to select |
| Split panes | `"tmux"` | tmux or iTerm2 | Each teammate gets own pane |

```json
// settings.json
{ "teammateMode": "in-process" }
```

```bash
# CLI override for single session
claude --teammate-mode in-process
```

**Auto-detection logic:**
1. `$TMUX` env var set → use tmux split panes
2. `$ITERM_SESSION_ID` set + `it2` available → use iTerm2
3. `which tmux` succeeds → use tmux
4. Fallback → in-process

**In-process navigation:**
- Shift+Up/Down → select teammate
- Enter → view teammate's session
- Escape → interrupt teammate's current turn
- Ctrl+T → toggle task list

**Split-pane navigation:**
- Click into pane to interact directly
- Each teammate has full terminal view

## Communication Patterns

**Direct message (`type: "message"`):** Send to one specific teammate via SendMessage. Use for targeted instructions, follow-ups, or redirecting approach.

**Broadcast (`type: "broadcast"`):** Send to all teammates simultaneously via SendMessage. Use sparingly — costs scale with team size. Good for: announcing shared decisions, requesting status updates.

**Automatic delivery:** Messages arrive at recipients automatically. Lead does not need to poll for updates.

**Idle notifications:** When a teammate finishes and stops, it automatically notifies the lead.

**Message type schemas:** See [assets/message-formats.yml](assets/message-formats.yml)

## Task Coordination

The shared task list coordinates work across the team. All agents see task status and can claim available work.

**Task lifecycle:** `pending` → `in_progress` → `completed`

**Assignment patterns:**
- Lead assigns explicitly ("Give task 3 to the security reviewer")
- Self-claim: after finishing a task, teammate picks next unassigned, unblocked task

**Dependencies:**
- Express with `blockedBy` field (array of task IDs)
- Auto-unblock: when blocking task completes, blocked tasks become available
- Enables sequential pipelines without polling

**File locking:** Task claiming uses file locking to prevent race conditions when multiple teammates try to claim simultaneously.

**Recommended task sizing:**
- 5-6 tasks per teammate for steady throughput
- Self-contained units producing clear deliverables
- Avoid: tasks too small (overhead > benefit) or too large (risk of wasted effort)

## Delegate Mode

Restricts the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks. Prevents lead from implementing tasks itself.

**Enable:** Press Shift+Tab to cycle into delegate mode after starting a team.

**When to use:**
- Lead keeps implementing tasks instead of waiting for teammates
- You want pure orchestration (break down work, assign, synthesize)
- Large teams where lead should focus on coordination

**Known bug:** Teammates spawned AFTER entering delegate mode inherit restricted tool access (lose Read, Write, Edit, Bash, Glob, Grep). **Workaround:** Spawn all teammates BEFORE pressing Shift+Tab.

**When to skip:**
- Small teams where lead can contribute implementation
- Lead needs to do synthesis work requiring file edits

## Plan Approval Workflow

Require teammates to plan before implementing. Teammate works in read-only plan mode until lead approves.

**Spawn with plan approval:**

```
Spawn