agent-teams.md +380 −0 created
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Orchestrate teams of Claude Code sessions
6
7> Coordinate multiple Claude Code instances working together as a team, with shared tasks, inter-agent messaging, and centralized management.
8
9<Warning>
10 Agent teams are experimental and disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your [settings.json](/en/settings) or environment. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior.
11</Warning>
12
13Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other.
14
15Unlike [subagents](/en/sub-agents), which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.
16
17This page covers:
18
19* [When to use agent teams](#when-to-use-agent-teams), including best use cases and how they compare with subagents
20* [Starting a team](#start-your-first-agent-team)
21* [Controlling teammates](#control-your-agent-team), including display modes, task assignment, and delegation
22* [Best practices for parallel work](#best-practices)
23
24## When to use agent teams
25
26Agent teams are most effective for tasks where parallel exploration adds real value. See [use case examples](#use-case-examples) for full scenarios. The strongest use cases are:
27
28* **Research and review**: multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other's findings
29* **New modules or features**: teammates can each own a separate piece without stepping on each other
30* **Debugging with competing hypotheses**: teammates test different theories in parallel and converge on the answer faster
31* **Cross-layer coordination**: changes that span frontend, backend, and tests, each owned by a different teammate
32
33Agent teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or [subagents](/en/sub-agents) are more effective.
34
35### Compare with subagents
36
37Both agent teams and [subagents](/en/sub-agents) let you parallelize work, but they operate differently. Choose based on whether your workers need to communicate with each other:
38
39| | Subagents | Agent teams |
40| :---------------- | :----------------------------------------------- | :-------------------------------------------------- |
41| **Context** | Own context window; results return to the caller | Own context window; fully independent |
42| **Communication** | Report results back to the main agent only | Teammates message each other directly |
43| **Coordination** | Main agent manages all work | Shared task list with self-coordination |
44| **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
45| **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
46
47Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.
48
49## Enable agent teams
50
51Agent teams are disabled by default. Enable them by setting the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable to `1`, either in your shell environment or through [settings.json](/en/settings):
52
53```json settings.json theme={null}
54{
55 "env": {
56 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
57 }
58}
59```
60
61## Start your first agent team
62
63After enabling agent teams, tell Claude to create an agent team and describe the task and the team structure you want in natural language. Claude creates the team, spawns teammates, and coordinates work based on your prompt.
64
65This example works well because the three roles are independent and can explore the problem without waiting on each other:
66
67```
68I'm designing a CLI tool that helps developers track TODO comments across
69their codebase. Create an agent team to explore this from different angles: one
70teammate on UX, one on technical architecture, one playing devil's advocate.
71```
72
73From there, Claude creates a team with a [shared task list](/en/interactive-mode#task-list), spawns teammates for each perspective, has them explore the problem, synthesizes findings, and attempts to [clean up the team](#clean-up-the-team) when finished.
74
75The lead's terminal lists all teammates and what they're working on. Use Shift+Up/Down to select a teammate and message them directly.
76
77If you want each teammate in its own split pane, see [Choose a display mode](#choose-a-display-mode).
78
79## Control your agent team
80
81Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions.
82
83### Choose a display mode
84
85Agent teams support two display modes:
86
87* **In-process**: all teammates run inside your main terminal. Use Shift+Up/Down to select a teammate and type to message them directly. Works in any terminal, no extra setup required.
88* **Split panes**: each teammate gets its own pane. You can see everyone's output at once and click into a pane to interact directly. Requires tmux, or iTerm2.
89
90<Note>
91 `tmux` has known limitations on certain operating systems and traditionally works best on macOS. Using `tmux -CC` in iTerm2 is the suggested entrypoint into `tmux`.
92</Note>
93
94The default is `"auto"`, which uses split panes if you're already running inside a tmux session, and in-process otherwise. The `"tmux"` setting enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal. To override, set `teammateMode` in your [settings.json](/en/settings):
95
96```json theme={null}
97{
98 "teammateMode": "in-process"
99}
100```
101
102To force in-process mode for a single session, pass it as a flag:
103
104```bash theme={null}
105claude --teammate-mode in-process
106```
107
108Split-pane mode requires either [tmux](https://github.com/tmux/tmux/wiki) or iTerm2 with the [`it2` CLI](https://github.com/mkusaka/it2). To install manually:
109
110* **tmux**: install through your system's package manager. See the [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) for platform-specific instructions.
111* **iTerm2**: install the [`it2` CLI](https://github.com/mkusaka/it2), then enable the Python API in **iTerm2 → Settings → General → Magic → Enable Python API**.
112
113### Specify teammates and models
114
115Claude decides the number of teammates to spawn based on your task, or you can specify exactly what you want:
116
117```
118Create a team with 4 teammates to refactor these modules in parallel.
119Use Sonnet for each teammate.
120```
121
122### Require plan approval for teammates
123
124For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves their approach:
125
126```
127Spawn an architect teammate to refactor the authentication module.
128Require plan approval before they make any changes.
129```
130
131When a teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either approves it or rejects it with feedback. If rejected, the teammate stays in plan mode, revises based on the feedback, and resubmits. Once approved, the teammate exits plan mode and begins implementation.
132
133The lead makes approval decisions autonomously. To influence the lead's judgment, give it criteria in your prompt, such as "only approve plans that include test coverage" or "reject plans that modify the database schema."
134
135### Use delegate mode
136
137Without delegate mode, the lead sometimes starts implementing tasks itself instead of waiting for teammates. Delegate mode prevents this by restricting the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks.
138
139This is useful when you want the lead to focus entirely on orchestration, such as breaking down work, assigning tasks, and synthesizing results, without touching code directly.
140
141To enable it, start a team first, then press Shift+Tab to cycle into delegate mode.
142
143### Talk to teammates directly
144
145Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.
146
147* **In-process mode**: use Shift+Up/Down to select a teammate, then type to send them a message. Press Enter to view a teammate's session, then Escape to interrupt their current turn. Press Ctrl+T to toggle the task list.
148* **Split-pane mode**: click into a teammate's pane to interact with their session directly. Each teammate has a full view of their own terminal.
149
150### Assign and claim tasks
151
152The shared task list coordinates work across the team. The lead creates tasks and teammates work through them. Tasks have three states: pending, in progress, and completed. Tasks can also depend on other tasks: a pending task with unresolved dependencies cannot be claimed until those dependencies are completed.
153
154The lead can assign tasks explicitly, or teammates can self-claim:
155
156* **Lead assigns**: tell the lead which task to give to which teammate
157* **Self-claim**: after finishing a task, a teammate picks up the next unassigned, unblocked task on its own
158
159Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously.
160
161### Shut down teammates
162
163To gracefully end a teammate's session:
164
165```
166Ask the researcher teammate to shut down
167```
168
169The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation.
170
171### Clean up the team
172
173When you're done, ask the lead to clean up:
174
175```
176Clean up the team
177```
178
179This removes the shared team resources. When the lead runs cleanup, it checks for active teammates and fails if any are still running, so shut them down first.
180
181<Warning>
182 Always use the lead to clean up. Teammates should not run cleanup because their team context may not resolve correctly, potentially leaving resources in an inconsistent state.
183</Warning>
184
185## How agent teams work
186
187This section covers the architecture and mechanics behind agent teams. If you want to start using them, see [Control your agent team](#control-your-agent-team) above.
188
189### How Claude starts agent teams
190
191There are two ways agent teams get started:
192
193* **You request a team**: give Claude a task that benefits from parallel work and explicitly ask for an agent team. Claude creates one based on your instructions.
194* **Claude proposes a team**: if Claude determines your task would benefit from parallel work, it may suggest creating a team. You confirm before it proceeds.
195
196In both cases, you stay in control. Claude won't create a team without your approval.
197
198### Architecture
199
200An agent team consists of:
201
202| Component | Role |
203| :------------ | :----------------------------------------------------------------------------------------- |
204| **Team lead** | The main Claude Code session that creates the team, spawns teammates, and coordinates work |
205| **Teammates** | Separate Claude Code instances that each work on assigned tasks |
206| **Task list** | Shared list of work items that teammates claim and complete |
207| **Mailbox** | Messaging system for communication between agents |
208
209See [Choose a display mode](#choose-a-display-mode) for display configuration options. Teammate messages arrive at the lead automatically.
210
211The system manages task dependencies automatically. When a teammate completes a task that other tasks depend on, blocked tasks unblock without manual intervention.
212
213Teams and tasks are stored locally:
214
215* **Team config**: `~/.claude/teams/{team-name}/config.json`
216* **Task list**: `~/.claude/tasks/{team-name}/`
217
218The team config contains a `members` array with each teammate's name, agent ID, and agent type. Teammates can read this file to discover other team members.
219
220### Permissions
221
222Teammates start with the lead's permission settings. If the lead runs with `--dangerously-skip-permissions`, all teammates do too. After spawning, you can change individual teammate modes, but you can't set per-teammate modes at spawn time.
223
224### Context and communication
225
226Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills. It also receives the spawn prompt from the lead. The lead's conversation history does not carry over.
227
228**How teammates share information:**
229
230* **Automatic message delivery**: when teammates send messages, they're delivered automatically to recipients. The lead doesn't need to poll for updates.
231* **Idle notifications**: when a teammate finishes and stops, they automatically notify the lead.
232* **Shared task list**: all agents can see task status and claim available work.
233
234**Teammate messaging:**
235
236* **message**: send a message to one specific teammate
237* **broadcast**: send to all teammates simultaneously. Use sparingly, as costs scale with team size.
238
239### Token usage
240
241Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates. For research, review, and new feature work, the extra tokens are usually worthwhile. For routine tasks, a single session is more cost-effective. See [agent team token costs](/en/costs#agent-team-token-costs) for usage guidance.
242
243## Use case examples
244
245These examples show how agent teams handle tasks where parallel exploration adds value.
246
247### Run a parallel code review
248
249A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously. The prompt assigns each teammate a distinct lens so they don't overlap:
250
251```
252Create an agent team to review PR #142. Spawn three reviewers:
253- One focused on security implications
254- One checking performance impact
255- One validating test coverage
256Have them each review and report findings.
257```
258
259Each reviewer works from the same PR but applies a different filter. The lead synthesizes findings across all three after they finish.
260
261### Investigate with competing hypotheses
262
263When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. The prompt fights this by making teammates explicitly adversarial: each one's job is not only to investigate its own theory but to challenge the others'.
264
265```
266Users report the app exits after one message instead of staying connected.
267Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
268each other to try to disprove each other's theories, like a scientific
269debate. Update the findings doc with whatever consensus emerges.
270```
271
272The debate structure is the key mechanism here. Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it.
273
274With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause.
275
276## Best practices
277
278### Give teammates enough context
279
280Teammates load project context automatically, including CLAUDE.md, MCP servers, and skills, but they don't inherit the lead's conversation history. See [Context and communication](#context-and-communication) for details. Include task-specific details in the spawn prompt:
281
282```
283Spawn a security reviewer teammate with the prompt: "Review the authentication module
284at src/auth/ for security vulnerabilities. Focus on token handling, session
285management, and input validation. The app uses JWT tokens stored in
286httpOnly cookies. Report any issues with severity ratings."
287```
288
289### Size tasks appropriately
290
291* **Too small**: coordination overhead exceeds the benefit
292* **Too large**: teammates work too long without check-ins, increasing risk of wasted effort
293* **Just right**: self-contained units that produce a clear deliverable, such as a function, a test file, or a review
294
295<Tip>
296 The lead breaks work into tasks and assigns them to teammates automatically. If it isn't creating enough tasks, ask it to split the work into smaller pieces. Having 5-6 tasks per teammate keeps everyone productive and lets the lead reassign work if someone gets stuck.
297</Tip>
298
299### Wait for teammates to finish
300
301Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this:
302
303```
304Wait for your teammates to complete their tasks before proceeding
305```
306
307### Start with research and review
308
309If you're new to agent teams, start with tasks that have clear boundaries and don't require writing code: reviewing a PR, researching a library, or investigating a bug. These tasks show the value of parallel exploration without the coordination challenges that come with parallel implementation.
310
311### Avoid file conflicts
312
313Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files.
314
315### Monitor and steer
316
317Check in on teammates' progress, redirect approaches that aren't working, and synthesize findings as they come in. Letting a team run unattended for too long increases the risk of wasted effort.
318
319## Troubleshooting
320
321### Teammates not appearing
322
323If teammates aren't appearing after you ask Claude to create a team:
324
325* In in-process mode, teammates may already be running but not visible. Press Shift+Down to cycle through active teammates.
326* Check that the task you gave Claude was complex enough to warrant a team. Claude decides whether to spawn teammates based on the task.
327* If you explicitly requested split panes, ensure tmux is installed and available in your PATH:
328 ```bash theme={null}
329 which tmux
330 ```
331* For iTerm2, verify the `it2` CLI is installed and the Python API is enabled in iTerm2 preferences.
332
333### Too many permission prompts
334
335Teammate permission requests bubble up to the lead, which can create friction. Pre-approve common operations in your [permission settings](/en/permissions) before spawning teammates to reduce interruptions.
336
337### Teammates stopping on errors
338
339Teammates may stop after encountering errors instead of recovering. Check their output using Shift+Up/Down in in-process mode or by clicking the pane in split mode, then either:
340
341* Give them additional instructions directly
342* Spawn a replacement teammate to continue the work
343
344### Lead shuts down before work is done
345
346The lead may decide the team is finished before all tasks are actually complete. If this happens, tell it to keep going. You can also tell the lead to wait for teammates to finish before proceeding if it starts doing work instead of delegating.
347
348### Orphaned tmux sessions
349
350If a tmux session persists after the team ends, it may not have been fully cleaned up. List sessions and kill the one created by the team:
351
352```bash theme={null}
353tmux ls
354tmux kill-session -t <session-name>
355```
356
357## Limitations
358
359Agent teams are experimental. Current limitations to be aware of:
360
361* **No session resumption with in-process teammates**: `/resume` and `/rewind` do not restore in-process teammates. After resuming a session, the lead may attempt to message teammates that no longer exist. If this happens, tell the lead to spawn new teammates.
362* **Task status can lag**: teammates sometimes fail to mark tasks as completed, which blocks dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.
363* **Shutdown can be slow**: teammates finish their current request or tool call before shutting down, which can take time.
364* **One team per session**: a lead can only manage one team at a time. Clean up the current team before starting a new one.
365* **No nested teams**: teammates cannot spawn their own teams or teammates. Only the lead can manage the team.
366* **Lead is fixed**: the session that creates the team is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership.
367* **Permissions set at spawn**: all teammates start with the lead's permission mode. You can change individual teammate modes after spawning, but you can't set per-teammate modes at spawn time.
368* **Split panes require tmux or iTerm2**: the default in-process mode works in any terminal. Split-pane mode isn't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.
369
370<Tip>
371 **`CLAUDE.md` works normally**: teammates read `CLAUDE.md` files from their working directory. Use this to provide project-specific guidance to all teammates.
372</Tip>
373
374## Next steps
375
376Explore related approaches for parallel work and delegation:
377
378* **Lightweight delegation**: [subagents](/en/sub-agents) spawn helper agents for research or verification within your session, better for tasks that don't need inter-agent coordination
379* **Manual parallel sessions**: [Git worktrees](/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) let you run multiple Claude Code sessions yourself without automated team coordination
380* **Compare approaches**: see the [subagent vs agent team](/en/features-overview#compare-similar-features) comparison for a side-by-side breakdown