agent-teams

# Agent Teams Coordinate multiple Claude Code sessions working on the same codebase simultaneously. ## Enable ```bash export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude # starts as team lead ``` The first session becomes the team lead. Subsequent sessions in the same repo join as teammates. ## Architecture ```text Team Lead (coordinates, delegates, reviews) ├── Teammate 1 (owns task A, messages lead + peers) ├── Teammate 2 (owns task B, messages lead + peers) └── Teammate 3 (owns task C, messages lead + peers) │ └── Shared: task list + mailbox + file locks ``` **Key difference from subagents:** Teammates are full Claude Code sessions. They have their own context window, can use all tools, and message each other directly — not just report back to a parent. ## Team Sizing | Team Size | Best For | |-----------|----------| | 2 | One builds, one reviews | | 3-5 | Parallel features across layers (API, UI, tests) | | > 5 | Coordination overhead outweighs parallelism | 3-5 teammates is the productive range. Beyond that, the lead spends more time coordinating than the team saves. **Task granularity:** Aim for 5-6 tasks per teammate. Fewer means underutilization; more means excessive context switching. ## Display Modes **In-process navigation:** - `Shift+Down` — cycle through teammates (wraps around) - See each teammate's current task and output **Split-pane (recommended for >2 teammates):** - tmux: `tmux split-window -h` per teammate - iTerm2: Cmd+D ...