---
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