177 lines
6.4 KiB
Markdown
177 lines
6.4 KiB
Markdown
---
|
||
title: "Agent Teams — Orchestrate Multiple Claude Code Sessions"
|
||
aliases: [agent-teams, claude-agent-teams, multi-session-teams]
|
||
tags: [claude-code, multi-agent, parallelism, orchestration, experimental]
|
||
sources: [raw/Orchestrate teams of Claude Code sessions.md]
|
||
created: 2026-04-17
|
||
updated: 2026-04-17
|
||
---
|
||
|
||
# Agent Teams
|
||
|
||
Agent teams let you coordinate multiple Claude Code instances working together. One session acts as **team lead**; the rest are **teammates** — independent sessions that communicate directly with each other via a shared task list and mailbox.
|
||
|
||
> **Experimental** — requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `settings.json` or env. Needs Claude Code v2.1.32+.
|
||
|
||
---
|
||
|
||
## Enabling
|
||
|
||
```json
|
||
{
|
||
"env": {
|
||
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
| Component | Role |
|
||
|-----------|------|
|
||
| **Team lead** | Main session — spawns teammates, owns task list, synthesizes results |
|
||
| **Teammates** | Independent Claude Code instances with their own context windows |
|
||
| **Task list** | Shared work items; teammates claim and complete them (`~/.claude/tasks/{team}/`) |
|
||
| **Mailbox** | Async messaging between any two agents by name |
|
||
|
||
- Team config stored at `~/.claude/teams/{team-name}/config.json` — do **not** edit by hand
|
||
- Task claiming uses file locking to prevent race conditions
|
||
- Dependencies are managed automatically: blocked tasks unblock when their dependency completes
|
||
|
||
---
|
||
|
||
## Agent Teams vs Subagents
|
||
|
||
| | Subagents | Agent Teams |
|
||
|--|-----------|-------------|
|
||
| **Communication** | Report results to main agent only | Teammates message each other directly |
|
||
| **Coordination** | Main agent manages all work | Shared task list with self-coordination |
|
||
| **Best for** | Focused tasks where only result matters | Complex work requiring discussion/collaboration |
|
||
| **Token cost** | Lower | Higher (each teammate is a separate Claude instance) |
|
||
|
||
Use [[wiki/claude-code/custom-subagents|subagents]] when workers only need to report back. Use agent teams when teammates need to share findings and challenge each other.
|
||
|
||
---
|
||
|
||
## When to Use
|
||
|
||
**Strong use cases (parallel exploration adds value):**
|
||
- Research & review — multiple angles investigated simultaneously
|
||
- New modules — each teammate owns a separate piece
|
||
- Debugging with competing hypotheses — teammates test theories in parallel
|
||
- Cross-layer changes — frontend, backend, tests each owned by a different teammate
|
||
|
||
**Avoid agent teams for:**
|
||
- Sequential tasks
|
||
- Same-file edits
|
||
- Work with many interdependencies (use a single session or subagents instead)
|
||
|
||
---
|
||
|
||
## Display Modes
|
||
|
||
| Mode | How | Requires |
|
||
|------|-----|----------|
|
||
| **in-process** (default) | All teammates in one terminal; `Shift+Down` cycles through | Nothing |
|
||
| **split-panes** | Each teammate gets its own pane | tmux or iTerm2 + `it2` CLI |
|
||
|
||
Override in `~/.claude.json`:
|
||
```json
|
||
{ "teammateMode": "in-process" }
|
||
```
|
||
Or per session: `claude --teammate-mode in-process`
|
||
|
||
---
|
||
|
||
## Control Patterns
|
||
|
||
### Spawn a team (natural language)
|
||
```text
|
||
Create an agent team: one teammate on UX, one on architecture, one as devil's advocate.
|
||
```
|
||
|
||
### Specify teammates and models
|
||
```text
|
||
Create a team with 4 teammates. Use Sonnet for each teammate.
|
||
```
|
||
|
||
### Require plan approval before implementation
|
||
```text
|
||
Spawn an architect teammate to refactor auth. Require plan approval before any changes.
|
||
```
|
||
Lead reviews → approves or rejects with feedback → teammate revises if rejected → implements when approved.
|
||
|
||
### Direct teammate messaging
|
||
- **In-process**: `Shift+Down` to cycle, type to message, `Enter` to view session, `Escape` to interrupt, `Ctrl+T` for task list
|
||
- **Split-pane**: click into a pane
|
||
|
||
### Shutdown & cleanup
|
||
```text
|
||
Ask the researcher teammate to shut down
|
||
Clean up the team # run after all teammates are stopped
|
||
```
|
||
Always run cleanup from the **lead**, not a teammate.
|
||
|
||
---
|
||
|
||
## Quality Gates via Hooks
|
||
|
||
| Hook | Trigger | Exit 2 = |
|
||
|------|---------|----------|
|
||
| `TeammateIdle` | Teammate about to go idle | Send feedback, keep teammate working |
|
||
| `TaskCreated` | Task being created | Block creation with feedback |
|
||
| `TaskCompleted` | Task being marked done | Block completion with feedback |
|
||
|
||
See [[wiki/claude-code/overview|Claude Code overview]] for general hooks documentation.
|
||
|
||
---
|
||
|
||
## Permissions & Context
|
||
|
||
- Teammates inherit the **lead's permission settings** at spawn time (including `--dangerously-skip-permissions`)
|
||
- Each teammate loads project context fresh: `CLAUDE.md`, MCP servers, skills — but **not** the lead's conversation history
|
||
- Include task-specific details in the spawn prompt
|
||
- Teammates can reference [[wiki/claude-code/custom-subagents|subagent definitions]] by name for reusable roles
|
||
|
||
---
|
||
|
||
## Best Practices
|
||
|
||
- **Start with 3–5 teammates** — balances parallelism with coordination overhead
|
||
- **5–6 tasks per teammate** — prevents context-switching overload
|
||
- **Break work by file ownership** — two teammates editing the same file causes overwrites
|
||
- **Begin with research/review tasks** if new to agent teams (no code-conflict risk)
|
||
- **Monitor and steer** — don't let teams run unattended too long
|
||
- **Tell the lead to wait** if it starts implementing instead of delegating: `"Wait for your teammates to complete their tasks before proceeding"`
|
||
|
||
---
|
||
|
||
## Limitations (Experimental)
|
||
|
||
- No session resumption for in-process teammates (`/resume`/`/rewind` don't restore them)
|
||
- Task status can lag — may need manual nudge
|
||
- Shutdown can be slow (teammate finishes current request first)
|
||
- One team per lead session
|
||
- No nested teams — teammates cannot spawn their own teams
|
||
- Lead is fixed for the team's lifetime
|
||
- Split panes not supported in VS Code terminal, Windows Terminal, or Ghostty
|
||
|
||
---
|
||
|
||
## Key Takeaways
|
||
|
||
- Agent teams are **experimental** and token-expensive — each teammate is a full Claude instance
|
||
- The core advantage over subagents: **teammates communicate directly** and share a task list with self-coordination
|
||
- **3–5 teammates, 5–6 tasks each** is the recommended starting size
|
||
- The **lead controls everything** — spawning, task assignment, cleanup; never run cleanup from a teammate
|
||
- Use **hooks** (`TeammateIdle`, `TaskCreated`, `TaskCompleted`) to enforce quality gates automatically
|
||
- Best ROI on research, parallel review, and competing-hypotheses debugging — not sequential or same-file work
|
||
|
||
---
|
||
|
||
## Sources
|
||
|
||
- `raw/Orchestrate teams of Claude Code sessions.md`
|
||
- Official docs: https://code.claude.com/docs/en/agent-teams
|