Orchestrate teams of Claude Code sessions changedagent-teams
Nearest release: v2.1.309, published 2 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 22 Oct 2026 22:51 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 19:07 UTC.
Upstream edited
Recorded here
Lines+63added
Lines−63removed
From line
4
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits42to this page, all time
The whole hunk
from line 4, old and new numbered
/
from line 4
44
55> [!WARNING]
66>
7> Agent teams are experimental and disabled by default. Enable them by setting `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your [settings.json](/docs/en/settings.md) or environment. Without that variable, no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior.
7> Agent teams are experimental and disabled by default. Enable them by setting `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your [settings.json](https://code.claude.com/docs/en/settings.md) or environment. Without that variable, no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates. Agent teams have [known limitations](#limitations) around session resumption, task coordination, and shutdown behavior.
88
99Agent 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. You can also talk to any teammate directly without going through the lead.
1010
11Before you set up a team, check whether a lighter option does the job. [Subagents](/docs/en/sub-agents.md) work within a single session, and with [cross-session messaging](/docs/en/cross-session-messaging.md) Claude can pass findings between the sessions you run yourself.
11Before you set up a team, check whether a lighter option does the job. [Subagents](https://code.claude.com/docs/en/sub-agents.md) work within a single session, and with [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md) Claude can pass findings between the sessions you run yourself.
1212
1313## When to use agent teams
1414
from line 19
1919* **Debugging with competing hypotheses**: teammates test different theories in parallel and converge on the answer faster
2020* **Cross-layer coordination**: changes that span frontend, backend, and tests, each owned by a different teammate
2121
22Agent 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](/docs/en/sub-agents.md) are more effective.
22Agent 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](https://code.claude.com/docs/en/sub-agents.md) are more effective.
2323
2424### Compare with subagents
2525
26Both agent teams and [subagents](/docs/en/sub-agents.md) let you parallelize work, but they operate differently. For separate sessions that pass messages to each other without a team, see [cross-session messaging](/docs/en/cross-session-messaging.md).
26Both agent teams and [subagents](https://code.claude.com/docs/en/sub-agents.md) let you parallelize work, but they operate differently. For separate sessions that pass messages to each other without a team, see [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md).
2727
2828
2929
from line 32
3232| | Subagents | Agent teams |
3333| :- | :- | :- |
3434| **Context** | Own context window; results return to the caller | Own context window; fully independent |
35| **Communication** | Return a result to the caller. Subagents that Claude [named](/docs/en/sub-agents.md#subagent-names) when it spawned them can also [message each other](/docs/en/sub-agents.md#what-loads-at-startup) | Teammates message each other directly |
36| **Coordination** | Main agent manages all work | Self-coordination through messages, plus a shared task list for [agents that have the Task tools](/docs/en/tools-reference.md#task-tool-availability) |
35| **Communication** | Return a result to the caller. Subagents that Claude [named](https://code.claude.com/docs/en/sub-agents.md#subagent-names) when it spawned them can also [message each other](https://code.claude.com/docs/en/sub-agents.md#what-loads-at-startup) | Teammates message each other directly |
36| **Coordination** | Main agent manages all work | Self-coordination through messages, plus a shared task list for [agents that have the Task tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability) |
3737| **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
3838| **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
3939
from line 41
4141
4242## Enable agent teams
4343
44Agent 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](/docs/en/settings.md):
44Agent 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](https://code.claude.com/docs/en/settings.md):
4545
4646```json settings.json theme={null}
4747{
from line 51
5151}
5252```
5353
54Enabling agent teams also changes ordinary delegation. Claude may [name a subagent](/docs/en/sub-agents.md#subagent-names) on its own, and while agent teams are enabled, a subagent that Claude names launches as a teammate, so teams can form even when you didn't ask for one. For more, see [How Claude starts agent teams](#how-claude-starts-agent-teams); to turn the behavior off, see [Claude spawns teammates instead of subagents](#claude-spawns-teammates-instead-of-subagents).
54Enabling agent teams also changes ordinary delegation. Claude may [name a subagent](https://code.claude.com/docs/en/sub-agents.md#subagent-names) on its own, and while agent teams are enabled, a subagent that Claude names launches as a teammate, so teams can form even when you didn't ask for one. For more, see [How Claude starts agent teams](#how-claude-starts-agent-teams); to turn the behavior off, see [Claude spawns teammates instead of subagents](#claude-spawns-teammates-instead-of-subagents).
5555
56Spawning teammates also requires an interactive session. In [non-interactive mode](/docs/en/headless.md) with the `-p` flag, including Agent SDK sessions, Claude doesn't spawn teammates, and a subagent that Claude names runs as an ordinary [subagent](/docs/en/sub-agents.md) even with agent teams enabled.
56Spawning teammates also requires an interactive session. In [non-interactive mode](https://code.claude.com/docs/en/headless.md) with the `-p` flag, including Agent SDK sessions, Claude doesn't spawn teammates, and a subagent that Claude names runs as an ordinary [subagent](https://code.claude.com/docs/en/sub-agents.md) even with agent teams enabled.
5757
5858## Start your first agent team
5959
from line 67
6767one on UX, one on technical architecture, one playing devil's advocate.
6868```
6969
70From there, Claude populates a [shared task list](/docs/en/interactive-mode.md#task-list) in a [session that has the Task tools](/docs/en/tools-reference.md#task-tool-availability), spawns teammates for each perspective, has them explore the problem, and synthesizes findings when finished.
70From there, Claude populates a [shared task list](https://code.claude.com/docs/en/interactive-mode.md#task-list) in a [session that has the Task tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability), spawns teammates for each perspective, has them explore the problem, and synthesizes findings when finished.
7171
72Claude may sometimes use [subagents](/docs/en/sub-agents.md) instead of creating a team. Subagents appear in the same agent panel as teammates, so the panel alone doesn't confirm a team formed. If Claude spawned subagents instead, ask again and explicitly request an agent team.
72Claude may sometimes use [subagents](https://code.claude.com/docs/en/sub-agents.md) instead of creating a team. Subagents appear in the same agent panel as teammates, so the panel alone doesn't confirm a team formed. If Claude spawned subagents instead, ask again and explicitly request an agent team.
7373
7474The lead's terminal lists teammates in the agent panel below the prompt input. From the panel:
7575
from line 102
102102
103103Set `"iterm2"` to use iTerm2 native split panes explicitly. This mode requires the [`it2` CLI](https://github.com/mkusaka/it2) and shows an error with the install command if `it2` is missing. The setup prompt that offers to install `it2` or switch to tmux appears under `"auto"` or `"tmux"` when your terminal is iTerm2 and tmux is available as a fallback.
104104
105To override the default, set [`teammateMode`](/docs/en/settings-reference#teammatemode) in `~/.claude/settings.json`:
105To override the default, set [`teammateMode`](https://code.claude.com/docs/en/settings-reference#teammatemode) in `~/.claude/settings.json`:
106106
107107```json theme={null}
108108{
from line 136
136136
1371371. The model your spawn prompt names for that teammate.
1381382. For a teammate spawned from a [subagent definition](#use-subagent-definitions-for-teammates), the definition's `model`, where `inherit` selects the lead's model.
1393. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/en/model-config#environment-variables), when it's set to anything other than `inherit`.
1393. [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/en/model-config#environment-variables), when it's set to anything other than `inherit`.
1401404. The lead's current model.
141141
142If an installed [mod](/docs/en/plugins/mods/overview.md) sets a model in its [`agent.spawn`](/docs/en/plugins/mods/reference#subagents) hook, Claude Code uses that model in place of the first source.
142If an installed [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) sets a model in its [`agent.spawn`](https://code.claude.com/docs/en/plugins/mods/reference#subagents) hook, Claude Code uses that model in place of the first source.
143143
144If you set [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](/docs/en/sub-agents#run-every-subagent-on-one-model), the first two sources don't apply. Claude Code picks every teammate's model from `CLAUDE_CODE_SUBAGENT_MODEL` when it's set to anything other than `inherit`, and from the lead's current model otherwise. Requires Claude Code v2.1.257 or later.
144If you set [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](https://code.claude.com/docs/en/sub-agents#run-every-subagent-on-one-model), the first two sources don't apply. Claude Code picks every teammate's model from `CLAUDE_CODE_SUBAGENT_MODEL` when it's set to anything other than `inherit`, and from the lead's current model otherwise. Requires Claude Code v2.1.257 or later.
145145
146146Before v2.1.251, `CLAUDE_CODE_SUBAGENT_MODEL` came first in this order.
147147
from line 149
149149>
150150> `teammateDefaultModel` was removed in v2.1.234; Claude Code ignores a leftover value. Name the model in your prompt instead.
151151
152Claude Code checks the model it selects for a teammate against your organization's [`availableModels`](/docs/en/model-config#restrict-model-selection) allowlist. When the allowlist blocks a value, Claude Code substitutes another model:
152Claude Code checks the model it selects for a teammate against your organization's [`availableModels`](https://code.claude.com/docs/en/model-config#restrict-model-selection) allowlist. When the allowlist blocks a value, Claude Code substitutes another model:
153153
154* **Family alias such as `opus`**: On the Anthropic API and Claude Platform on AWS, Claude Code runs the teammate on the newest version of that family the allowlist permits. On providers with provider-specific model IDs, where the [substitution doesn't operate](/docs/en/model-config.md#restrict-model-selection), a blocked alias falls back like any other blocked value per the next bullet
154* **Family alias such as `opus`**: On the Anthropic API and Claude Platform on AWS, Claude Code runs the teammate on the newest version of that family the allowlist permits. On providers with provider-specific model IDs, where the [substitution doesn't operate](https://code.claude.com/docs/en/model-config.md#restrict-model-selection), a blocked alias falls back like any other blocked value per the next bullet
155155* **Any other blocked value, including a family alias on providers where the substitution doesn't operate, or one whose family has no permitted version**: Claude Code runs the teammate on the lead's model instead. If you set `CLAUDE_CODE_SUBAGENT_MODEL`, Claude Code tries that model first, under these same rules
156156
157By default, teammates inherit the lead's [effort level](/docs/en/model-config.md#adjust-effort-level). In split-pane mode this applies from v2.1.186; earlier versions did not pass the lead's session effort to split-pane teammates.
157By default, teammates inherit the lead's [effort level](https://code.claude.com/docs/en/model-config.md#adjust-effort-level). In split-pane mode this applies from v2.1.186; earlier versions did not pass the lead's session effort to split-pane teammates.
158158
159159### Have teammates plan before implementing
160160
161For complex or risky tasks, you can have teammates plan before implementing. A teammate that Claude spawns while the lead is in [plan mode](/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) works in read-only plan mode until its plan is ready. Switch the lead into plan mode first, then ask for the teammate:
161For complex or risky tasks, you can have teammates plan before implementing. A teammate that Claude spawns while the lead is in [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) works in read-only plan mode until its plan is ready. Switch the lead into plan mode first, then ask for the teammate:
162162
163163```text wrap theme={null}
164164Spawn an architect teammate to refactor the authentication module.
from line 166
166166
167167When that teammate finishes planning, it sends a plan approval request to the lead. If you haven't changed that teammate's permission mode since it was spawned, Claude Code approves the plan as soon as the request arrives, without the lead reviewing it. The teammate's edits and commands still go through the permission prompts described in [Permissions](#permissions). Once approved, the teammate exits plan mode and begins implementation.
168168
169If you put a running in-process teammate in plan mode by pressing [`Shift+Tab`](/docs/en/permission-modes#switch-permission-modes) while viewing its session, the lead reviews that run's plan instead of Claude Code approving it. You aren't asked to approve it; the lead approves it or sends it back for revision.
169If you put a running in-process teammate in plan mode by pressing [`Shift+Tab`](https://code.claude.com/docs/en/permission-modes#switch-permission-modes) while viewing its session, the lead reviews that run's plan instead of Claude Code approving it. You aren't asked to approve it; the lead approves it or sends it back for revision.
170170
171171### Talk to teammates directly
172172
from line 175
175175* **In-process mode**: use the up and down arrow keys in the agent panel to select a teammate, then press Enter to view its session and type to send it a message. Press `x` on a selected teammate to stop it. Press Ctrl+T to toggle the task list.
176176* **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.
177177
178While you're viewing an in-process teammate, plain text and [skills](/docs/en/skills.md) go to that teammate, and built-in commands go to the lead's session, with these safeguards:
178While you're viewing an in-process teammate, plain text and [skills](https://code.claude.com/docs/en/skills.md) go to that teammate, and built-in commands go to the lead's session, with these safeguards:
179179
180180* `/compact`, `/clear`, and `/rewind` act on the lead's conversation, so Claude Code asks you to confirm before running one of them from this view.
181181* `/model` and `/fast` set the lead's model and fast mode, not the teammate's, so they don't run from this view. A notice tells you why.
from line 186
186186
187187The 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.
188188
189Agents [without the Task tools](/docs/en/tools-reference.md#task-tool-availability) coordinate through messages instead of the shared task list.
189Agents [without the Task tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability) coordinate through messages instead of the shared task list.
190190
191191The lead can assign tasks explicitly, or teammates can self-claim:
192192
from line 209
209209
210210### Enforce quality gates with hooks
211211
212Use [hooks](/docs/en/hooks.md) to enforce rules when teammates finish work or tasks are created or completed:
212Use [hooks](https://code.claude.com/docs/en/hooks.md) to enforce rules when teammates finish work or tasks are created or completed:
213213
214* [`TeammateIdle`](/docs/en/hooks#teammateidle): runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.
215* [`TaskCreated`](/docs/en/hooks#taskcreated): runs when a task is being created. Exit with code 2 to prevent creation and send feedback.
216* [`TaskCompleted`](/docs/en/hooks#taskcompleted): runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.
214* [`TeammateIdle`](https://code.claude.com/docs/en/hooks#teammateidle): runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working.
215* [`TaskCreated`](https://code.claude.com/docs/en/hooks#taskcreated): runs when a task is being created. Exit with code 2 to prevent creation and send feedback.
216* [`TaskCompleted`](https://code.claude.com/docs/en/hooks#taskcompleted): runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.
217217
218218## How agent teams work
219219
from line 221
221221
222222### How Claude starts agent teams
223223
224To start a team, ask Claude for teammates. Claude launches a teammate when it calls the [Agent tool](/docs/en/tools-reference.md) with a [`name`](/docs/en/sub-agents#subagent-names) while agent teams are enabled, unless the call is a [fork](/docs/en/sub-agents.md#fork-the-current-conversation) or passes `isolation` on the call itself. Claude Code doesn't ask you to confirm the launch.
224To start a team, ask Claude for teammates. Claude launches a teammate when it calls the [Agent tool](https://code.claude.com/docs/en/tools-reference.md) with a [`name`](https://code.claude.com/docs/en/sub-agents#subagent-names) while agent teams are enabled, unless the call is a [fork](https://code.claude.com/docs/en/sub-agents.md#fork-the-current-conversation) or passes `isolation` on the call itself. Claude Code doesn't ask you to confirm the launch.
225225
226226Claude also names ordinary subagents on its own so it can message them later. Those calls follow the same rule, so teams can form even when you didn't ask for one. If you want subagents instead, [turn agent teams off](#claude-spawns-teammates-instead-of-subagents).
227227
from line 238
238238
239239Each agent's mailbox is a JSON file at `~/.claude/teams/{team-name}/inboxes/{agent-name}.json`. Claude Code validates every entry when it reads a mailbox file. Entries that don't match the message format are reported as errors and removed from the file; the valid messages are still delivered.
240240
241Claude Code reports a message as sent only when the write to the recipient's mailbox file succeeds, whether the message is plain text or a structured protocol message such as a plan approval or shutdown request. When the write fails, for example because the disk is full or the mailbox directory isn't writable, the sending agent receives an error and nothing is sent. See [Failed to write to a teammate's inbox](/docs/en/errors.md#failed-to-write-to-a-teammate-inbox) for the error messages and recovery steps.
241Claude Code reports a message as sent only when the write to the recipient's mailbox file succeeds, whether the message is plain text or a structured protocol message such as a plan approval or shutdown request. When the write fails, for example because the disk is full or the mailbox directory isn't writable, the sending agent receives an error and nothing is sent. See [Failed to write to a teammate's inbox](https://code.claude.com/docs/en/errors.md#failed-to-write-to-a-teammate-inbox) for the error messages and recovery steps.
242242
243243Claude Code manages task dependencies automatically: when a teammate completes a task that other tasks depend on, it unblocks the dependent tasks without any action from you.
244244
from line 245
245245Teams and tasks are stored locally under a session-derived name. The name is `session-` followed by the first eight characters of the session ID:
246246
247247* **Team config**: `~/.claude/teams/{team-name}/config.json`. Claude Code removes the team config directory when the session ends.
248* **Task list**: `~/.claude/tasks/{team-name}/`. This directory stays on disk after the session ends. To change [how long Claude Code keeps it](/docs/en/claude-directory.md#cleaned-up-automatically), set [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays).
248* **Task list**: `~/.claude/tasks/{team-name}/`. This directory stays on disk after the session ends. To change [how long Claude Code keeps it](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically), set [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays).
249249
250250Claude Code generates both of these automatically at session startup and updates them as teammates join, go idle, or leave.
251251
from line 253
253253
254254To define reusable teammate roles, use [subagent definitions](#use-subagent-definitions-for-teammates) instead.
255255
256The team config contains a `members` array with each member's name and agent ID. The lead's entry always carries the agent type `team-lead`. A teammate's entry carries whatever agent type the lead named when spawning it, whether a [built-in type](/docs/en/sub-agents.md#built-in-subagents) or a [subagent definition](#use-subagent-definitions-for-teammates), and omits the field when the lead named none. Teammates can read this file to discover other team members.
256The team config contains a `members` array with each member's name and agent ID. The lead's entry always carries the agent type `team-lead`. A teammate's entry carries whatever agent type the lead named when spawning it, whether a [built-in type](https://code.claude.com/docs/en/sub-agents.md#built-in-subagents) or a [subagent definition](#use-subagent-definitions-for-teammates), and omits the field when the lead named none. Teammates can read this file to discover other team members.
257257
258258There is no project-level equivalent of the team config. A file like `.claude/teams/teams.json` in your project directory is not recognized as configuration; Claude treats it as an ordinary file.
259259
260260### Use subagent definitions for teammates
261261
262When spawning a teammate in either display mode, you can reference a [subagent](/docs/en/sub-agents.md) type from the project, user, managed, or plugin [subagent scope](/docs/en/sub-agents.md#choose-the-subagent-scope). This lets you define a role once, such as a security-reviewer or test-runner, and reuse it both as a delegated subagent and as an agent team teammate.
262When spawning a teammate in either display mode, you can reference a [subagent](https://code.claude.com/docs/en/sub-agents.md) type from the project, user, managed, or plugin [subagent scope](https://code.claude.com/docs/en/sub-agents.md#choose-the-subagent-scope). This lets you define a role once, such as a security-reviewer or test-runner, and reuse it both as a delegated subagent and as an agent team teammate.
263263
264264To use a subagent definition, name it when you ask Claude to spawn the teammate:
265265
from line 269
269269
270270Claude Code reads the subagent definition you named and applies these parts of it to the teammate. Where a part depends on the teammate's [display mode](#choose-a-display-mode), the entry says so:
271271
272* **`tools`**: Claude Code limits the teammate to the tools in the definition's `tools` list. For an in-process teammate, Claude Code adds `SendMessage` to that list, and in a [session that has the Task tools](/docs/en/tools-reference.md#task-tool-availability) it adds `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` too.
272* **`tools`**: Claude Code limits the teammate to the tools in the definition's `tools` list. For an in-process teammate, Claude Code adds `SendMessage` to that list, and in a [session that has the Task tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability) it adds `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` too.
273273* **`model`**: Claude Code uses the definition's `model` in either display mode when your spawn prompt doesn't name one. See [how Claude Code picks a teammate's model](#specify-teammates-and-models).
274274* **`disallowedTools`**: for an in-process teammate, Claude Code removes the tools in the definition's `disallowedTools` from the teammate's set. `SendMessage` and the Task tools it adds stay available even when the list names them.
275* **`effort`**: for an in-process teammate, Claude Code applies the definition's [`effort`](/docs/en/sub-agents#supported-frontmatter-fields) under the [frontmatter effort rules](/docs/en/model-config.md#set-the-effort-level).
276* **`autoCompactWindow`**: for an in-process teammate, Claude Code applies the definition's [`autoCompactWindow`](/docs/en/sub-agents#supported-frontmatter-fields) under [that field's rules](/docs/en/sub-agents.md#subagent-auto-compact-window). A split-pane teammate ignores the field. Requires Claude Code v2.1.296 or later.
275* **`effort`**: for an in-process teammate, Claude Code applies the definition's [`effort`](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields) under the [frontmatter effort rules](https://code.claude.com/docs/en/model-config.md#set-the-effort-level).
276* **`autoCompactWindow`**: for an in-process teammate, Claude Code applies the definition's [`autoCompactWindow`](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields) under [that field's rules](https://code.claude.com/docs/en/sub-agents.md#subagent-auto-compact-window). A split-pane teammate ignores the field. Requires Claude Code v2.1.296 or later.
277277* **Body**: for an in-process teammate, Claude Code appends the definition's body to its default system prompt as additional instructions. For a split-pane teammate, Claude Code uses the body in place of its default system prompt.
278278* **`skills`**: Claude Code doesn't apply the definition's `skills` to a teammate in either display mode. The teammate loads skills from your project and user settings.
279* **`mcpServers`**: for a split-pane teammate, Claude Code applies the definition's `mcpServers` under the [rules for that field](/docs/en/sub-agents.md#scope-mcp-servers-to-a-subagent), which cover a session started with `--agent` as well. An in-process teammate ignores the field and loads MCP servers from your project and user settings.
279* **`mcpServers`**: for a split-pane teammate, Claude Code applies the definition's `mcpServers` under the [rules for that field](https://code.claude.com/docs/en/sub-agents.md#scope-mcp-servers-to-a-subagent), which cover a session started with `--agent` as well. An in-process teammate ignores the field and loads MCP servers from your project and user settings.
280280
281281When Claude messages an in-process teammate that is no longer running, Claude Code brings it back in the same session, restores any conversation saved for it, and gives it the message as its next prompt. After you resume a session, teammates aren't brought back this way, per [the resume limitation](#limitations).
282282
283For a teammate it brings back, Claude Code re-applies a definition that came from a project's `.claude/agents/` directory or an `--add-dir` directory only if you've [trusted the folder the agent file is in](/docs/en/permissions.md#what-runs-before-you-trust-a-folder). Trusting a parent folder doesn't count. Until then, the teammate comes back with none of the definition's tools or instructions, keeping only the tools Claude Code adds to every in-process teammate. See [the teammate's agent definition was not restored](/docs/en/errors.md#teammate-agent-definition-not-restored) for the notice text.
283For a teammate it brings back, Claude Code re-applies a definition that came from a project's `.claude/agents/` directory or an `--add-dir` directory only if you've [trusted the folder the agent file is in](https://code.claude.com/docs/en/permissions.md#what-runs-before-you-trust-a-folder). Trusting a parent folder doesn't count. Until then, the teammate comes back with none of the definition's tools or instructions, keeping only the tools Claude Code adds to every in-process teammate. See [the teammate's agent definition was not restored](https://code.claude.com/docs/en/errors.md#teammate-agent-definition-not-restored) for the notice text.
284284
285285### Permissions
286286
287Teammates start with the lead's permission mode, except [`dontAsk` mode](/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), which they don't inherit. If the lead runs with `--dangerously-skip-permissions`, all teammates do too. After spawning, you can change an individual teammate's permission mode, but you can't set per-teammate permission modes at spawn time.
287Teammates start with the lead's permission mode, except [`dontAsk` mode](https://code.claude.com/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode), which they don't inherit. If the lead runs with `--dangerously-skip-permissions`, all teammates do too. After spawning, you can change an individual teammate's permission mode, but you can't set per-teammate permission modes at spawn time.
288288
289An [in-process](#choose-a-display-mode) teammate runs under the lead's live allow and deny rules, so [`--disallowedTools`](/docs/en/cli-reference#cli-flags), `--tools`, and `--allowedTools` all apply to it. For a split-pane teammate, check each flag:
289An [in-process](#choose-a-display-mode) teammate runs under the lead's live allow and deny rules, so [`--disallowedTools`](https://code.claude.com/docs/en/cli-reference#cli-flags), `--tools`, and `--allowedTools` all apply to it. For a split-pane teammate, check each flag:
290290
291291* **`--disallowedTools` and `--tools`**: the teammate starts with the lead's command-line deny rules and tool list. Requires Claude Code v2.1.309 or later.
292* **`--allowedTools`**: Claude Code doesn't pass this flag to a split-pane teammate, so an action you allowed with it alone isn't pre-approved there. To approve those actions ahead of time, put the rules under `permissions.allow` in [`--settings`](/docs/en/settings#change-a-setting-for-one-session) when you start the lead. For example, run `claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}'` in your shell. The rules apply to the lead and each split-pane teammate for that session.
292* **`--allowedTools`**: Claude Code doesn't pass this flag to a split-pane teammate, so an action you allowed with it alone isn't pre-approved there. To approve those actions ahead of time, put the rules under `permissions.allow` in [`--settings`](https://code.claude.com/docs/en/settings#change-a-setting-for-one-session) when you start the lead. For example, run `claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}'` in your shell. The rules apply to the lead and each split-pane teammate for that session.
293293
294294Teammate permission prompts appear in the lead session, so approve them there yourself. You don't need to approve [a teammate's plan](#have-teammates-plan-before-implementing).
295295
296296#### Messages between agents
297297
298When one agent sends another a message over `SendMessage`, Claude Code tells the receiving agent the message came from another Claude session, not from you. A teammate can't approve a permission prompt or supply consent on your behalf, and a teammate that was denied an action can't relay it to another teammate to bypass the check. The same rules apply to a message that arrives from [one of your other Claude Code sessions](/docs/en/cross-session-messaging.md#how-a-session-treats-an-incoming-message), outside the team entirely.
298When one agent sends another a message over `SendMessage`, Claude Code tells the receiving agent the message came from another Claude session, not from you. A teammate can't approve a permission prompt or supply consent on your behalf, and a teammate that was denied an action can't relay it to another teammate to bypass the check. The same rules apply to a message that arrives from [one of your other Claude Code sessions](https://code.claude.com/docs/en/cross-session-messaging.md#how-a-session-treats-an-incoming-message), outside the team entirely.
299299
300In [auto mode](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), the classifier applies two checks to messages between agents:
300In [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode), the classifier applies two checks to messages between agents:
301301
302302* It treats an approval claim relayed from another agent as untrusted input rather than confirmation from you.
303303* It reviews each message before Claude Code delivers it, whether a plain message or a structured protocol message such as a shutdown request or plan approval response. A message it blocks never reaches the recipient.
from line 304
304304
305305### Context and communication
306306
307Each 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. If you start the lead with [`--setting-sources`](/docs/en/cli-reference#cli-flags), teammates load from the same restricted list of sources. Before v2.1.281, [split-pane](#choose-a-display-mode) teammates loaded every settings source.
307Each 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. If you start the lead with [`--setting-sources`](https://code.claude.com/docs/en/cli-reference#cli-flags), teammates load from the same restricted list of sources. Before v2.1.281, [split-pane](#choose-a-display-mode) teammates loaded every settings source.
308308
309309A teammate also receives the spawn prompt from the lead. The lead's conversation history does not carry over.
310310
from line 312
312312
313313* **Automatic message delivery**: when teammates send messages, they're delivered automatically to recipients. The lead doesn't need to poll for updates.
314314* **Idle notifications**: when a teammate finishes and stops, it automatically notifies the lead and includes its final answer in the notification. A teammate whose turn ends on an API error notifies the lead that it failed and includes the error text.
315* **Shared task list**: [agents that have the Task tools](/docs/en/tools-reference.md#task-tool-availability) can see task status and claim available work.
315* **Shared task list**: [agents that have the Task tools](https://code.claude.com/docs/en/tools-reference.md#task-tool-availability) can see task status and claim available work.
316316* **Teammate messaging**: send a message to one specific teammate by name. To reach everyone, send one message per recipient.
317317
318318The lead assigns every teammate a name when it spawns them, and any teammate can message any other by that name. To get predictable names you can reference in later prompts, tell the lead what to call each teammate in your spawn instruction.
from line 319
319319
320320### Token usage
321321
322Agent 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](/docs/en/costs.md#agent-team-token-costs) for usage guidance.
322Agent 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](https://code.claude.com/docs/en/costs.md#agent-team-token-costs) for usage guidance.
323323
324An in-process teammate's requests fall outside the main conversation's [cache TTL bucket](/docs/en/prompt-caching.md#which-ttl-each-request-gets), so its cache holds for five minutes by default, including on a Claude subscription. To keep it for an hour, set [`subagentPromptCacheTtl`](/docs/en/settings-reference#subagentpromptcachettl) to `1h`. The API bills 1-hour cache writes at a higher rate.
324An in-process teammate's requests fall outside the main conversation's [cache TTL bucket](https://code.claude.com/docs/en/prompt-caching.md#which-ttl-each-request-gets), so its cache holds for five minutes by default, including on a Claude subscription. To keep it for an hour, set [`subagentPromptCacheTtl`](https://code.claude.com/docs/en/settings-reference#subagentpromptcachettl) to `1h`. The API bills 1-hour cache writes at a higher rate.
325325
326326## Use case examples
327327
from line 373
373373
374374There's no hard limit on the number of teammates, but practical constraints apply:
375375
376* **Token costs scale linearly**: each teammate has its own context window and consumes tokens independently. See [agent team token costs](/docs/en/costs.md#agent-team-token-costs) for details.
376* **Token costs scale linearly**: each teammate has its own context window and consumes tokens independently. See [agent team token costs](https://code.claude.com/docs/en/costs.md#agent-team-token-costs) for details.
377377* **Coordination overhead increases**: more teammates means more communication, task coordination, and potential for conflicts
378378* **Diminishing returns**: beyond a certain point, additional teammates don't speed up work proportionally
379379
from line 444
444444
445445Setting the variable to `0` in your user `settings.json` overrides a shell export. Other settings sources can still enable agent teams:
446446
447* **Higher-precedence settings files**: project settings, local settings, and a `--settings` payload apply after user settings, so an `env` entry that sets the variable to `1` in any of them wins. See [Settings precedence](/docs/en/settings.md#settings-precedence).
448* **Managed settings**: [managed settings](/docs/en/server-managed-settings.md) apply after every other source. If your organization enables agent teams there, ask your administrator to change the managed value.
447* **Higher-precedence settings files**: project settings, local settings, and a `--settings` payload apply after user settings, so an `env` entry that sets the variable to `1` in any of them wins. See [Settings precedence](https://code.claude.com/docs/en/settings.md#settings-precedence).
448* **Managed settings**: [managed settings](https://code.claude.com/docs/en/server-managed-settings.md) apply after every other source. If your organization enables agent teams there, ask your administrator to change the managed value.
449449
450After the change, Claude may still name subagents, and the name keeps working as a [`SendMessage` address](/docs/en/sub-agents#resume-subagents). Claude receives each subagent's result when it completes.
450After the change, Claude may still name subagents, and the name keeps working as a [`SendMessage` address](https://code.claude.com/docs/en/sub-agents#resume-subagents). Claude receives each subagent's result when it completes.
451451
452452### Too many permission prompts
453453
454Teammate permission requests bubble up to the lead, which can create friction. Pre-approve common operations in your [permission settings](/docs/en/permissions.md) before spawning teammates to reduce interruptions.
454Teammate permission requests bubble up to the lead, which can create friction. Pre-approve common operations in your [permission settings](https://code.claude.com/docs/en/permissions.md) before spawning teammates to reduce interruptions.
455455
456456### Agents stopping early
457457
from line 482
482482* **Shutdown can be slow**: teammates finish their current request or tool call before shutting down, which can take time.
483483* **One team per session**: a session has exactly one team, scoped to that session. You can't create additional named teams or share a team across sessions.
484484* **No nested teams**: teammates cannot spawn their own teammates. Only the lead can manage the team.
485* **No background subagents from in-process teammates**: an in-process teammate's own subagents run in the foreground, because a teammate's background work can't outlive the lead's process. Claude Code returns an error when a teammate spawns a subagent whose definition sets `background: true`. A teammate's `run_in_background: true` request also fails, either with an error or by running silently in the foreground. Subagents launched from the main conversation follow the [background default](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background).
485* **No background subagents from in-process teammates**: an in-process teammate's own subagents run in the foreground, because a teammate's background work can't outlive the lead's process. Claude Code returns an error when a teammate spawns a subagent whose definition sets `background: true`. A teammate's `run_in_background: true` request also fails, either with an error or by running silently in the foreground. Subagents launched from the main conversation follow the [background default](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background).
486486* **Lead is fixed**: the main session is the lead for its lifetime. You can't promote a teammate to lead or transfer leadership.
487487* **Permissions set at spawn**: teammates start with the permission mode described under [Permissions](#permissions). You can change an individual teammate's permission mode after spawning, but you can't set per-teammate permission modes at spawn time.
488488* **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.
from line 491
491491
492492Explore related approaches for parallel work and delegation:
493493
494* **Lightweight delegation**: [subagents](/docs/en/sub-agents.md) spawn helper agents for research or verification within your session, better for tasks that don't need inter-agent coordination
495* **Messaging between your own sessions**: [cross-session messaging](/docs/en/cross-session-messaging.md) lets Claude pass findings between the sessions you run yourself
496* **Manual parallel sessions**: [Git worktrees](/docs/en/worktrees.md) let you run multiple Claude Code sessions yourself without automated team coordination
494* **Lightweight delegation**: [subagents](https://code.claude.com/docs/en/sub-agents.md) spawn helper agents for research or verification within your session, better for tasks that don't need inter-agent coordination
495* **Messaging between your own sessions**: [cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging.md) lets Claude pass findings between the sessions you run yourself
496* **Manual parallel sessions**: [Git worktrees](https://code.claude.com/docs/en/worktrees.md) let you run multiple Claude Code sessions yourself without automated team coordination
497497
No line in this hunk matches that.