Orchestrate teams of Claude Code sessions changedagent-teams
Nearest release: v2.1.233, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+36added
Lines−5removed
From line
57
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits39to this page, all time
### Claude spawns teammates instead of subagents
The whole hunk
from line 57, old and new numbered
/
from line 57
5757}
5858```
5959
60Enabling agent teams also changes ordinary delegation. Claude may [name a subagent](/docs/en/sub-agents#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 the exact conditions, 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).
61
62Spawning teammates also requires an interactive session. In [non-interactive mode](/docs/en/headless) 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) even with agent teams enabled.
63
6064## Start your first agent team
6165
6266After enabling agent teams, describe the task and the teammates you want in natural language. Claude spawns them and coordinates work based on your prompt.
from line 208
204208
205209### How Claude starts agent teams
206210
207An agent team forms when the first teammate is spawned, with the main session acting as the lead. There are two ways teammates get spawned:
211An agent team forms when the first teammate is spawned, with the main session acting as the lead. Claude spawns a teammate the same way it spawns a [subagent](/docs/en/sub-agents), by calling the [Agent tool](/docs/en/tools-reference), adding a `name` parameter to the call. Claude Code doesn't ask you to confirm before the teammate starts. Claude adds a `name` in situations such as:
208212
209213* **You request teammates**: give Claude a task that benefits from parallel work and explicitly ask for teammates. Claude spawns them based on your instructions.
210* **Claude proposes teammates**: if Claude determines your task would benefit from parallel work, it may suggest spawning teammates. You confirm before it proceeds.
214* **Claude proposes teammates**: if Claude determines your task would benefit from parallel work, it may suggest a team and spawn teammates.
215* **Claude names a subagent**: Claude may name a subagent on its own so it can [message it later](/docs/en/sub-agents#resume-subagents), whether or not agent teams are enabled. In an interactive session with agent teams enabled, the subagent launches as a teammate unless the call also spawns a [fork](/docs/en/sub-agents#fork-the-current-conversation) or uses [`isolation`](/docs/en/worktrees), so a team can form during ordinary delegation you never framed as team work.
211216
212In both cases, you stay in control. Claude won't spawn teammates without your approval.
217If teams form where you expect ordinary subagents, see [Claude spawns teammates instead of subagents](#claude-spawns-teammates-instead-of-subagents).
213218
214219### Architecture
215220
from line 286
281286**How teammates share information:**
282287
283288* **Automatic message delivery**: when teammates send messages, they're delivered automatically to recipients. The lead doesn't need to poll for updates.
284* **Idle notifications**: when a teammate finishes and stops, it automatically notifies the lead. As of v2.1.198, a teammate whose turn ends on an API error notifies the lead that it failed and includes the error text, instead of appearing to finish normally.
289* **Idle notifications**: when a teammate finishes and stops, it automatically notifies the lead. The notification doesn't carry the teammate's output; a teammate shares results by messaging the lead or updating the shared task list. As of v2.1.198, a teammate whose turn ends on an API error notifies the lead that it failed and includes the error text, instead of appearing to finish normally.
285290* **Shared task list**: all agents can see task status and claim available work.
286291* **Teammate messaging**: send a message to one specific teammate by name. To reach everyone, send one message per recipient.
287292
from line 398
393398 which tmux
394399 ```
395400* For iTerm2, verify the `it2` CLI is installed and the Python API is enabled in iTerm2 preferences.
401
402### Claude spawns teammates instead of subagents
403
404While agent teams are enabled, a subagent that Claude names in the lead's session launches as a teammate. Claude [can name subagents on its own](#how-claude-starts-agent-teams), so this can happen during delegation you never framed as team work. Subagents and teammates report back differently:
405
406* **Subagents**: Claude receives the subagent's result when it completes.
407* **Teammates**: the [idle notification](#context-and-communication) reports that the teammate stopped, without its output.
408
409An orchestration flow that waits on subagent results can stall. To make named subagents launch as subagents again, turn agent teams off by setting `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to `0`:
410
411```json settings.json theme={null}
412{
413 "env": {
414 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
415 }
416}
417```
418
419You don't need to start a new session: Claude Code reapplies settings-file `env` values to the running session when you save, and rereads the variable each time Claude spawns a subagent, so the next subagent Claude names launches as a subagent.
420
421Setting the variable to `0` in your user `settings.json` overrides a shell export. Other settings sources can still enable agent teams:
422
423* **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#settings-precedence).
424* **Managed settings**: [managed settings](/docs/en/server-managed-settings) apply after every other source. If your organization enables agent teams there, ask your administrator to change the managed value.
425
426After 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.
396427
397428### Too many permission prompts
398429
No line in this hunk matches that.