Follow Discord
Sweep 02 Oct 2026 · 18:55Z Build v2.1.288 509 read Stable v2.1.285 Latest v2.1.287 Next v2.1.288 Feeds RSS JSON llms.txt llms-full.txt Unofficial
HomeDocsClaude Code CLI 25 Sep 2026
One change · claude-code

Orchestrate teams of Claude Code sessions changedagent-teams

Nearest release: v2.1.283, published 3 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 25 Sep 2026 22:12 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 28 Sep 2026 23:37 UTC.

Upstream edited
Recorded here
Lines+12added
Lines−12removed
From line 31 where the diff opens
First seen 14 Aug 2026 this site's first read of the page
Recorded edits29to this page, all time

The whole hunk

from line 31, old and new numbered
/
lines
from line 31
3131 <img src="https://mintcdn.com/claude-code/nsvRFSDNfpSU5nT7/images/subagents-vs-agent-teams-dark.png?fit=max&auto=format&n=nsvRFSDNfpSU5nT7&q=85&s=d573a037540f2ada6a9ae7d8285b46fd" className="hidden dark:block" alt="Diagram comparing subagent and agent team architectures. Subagents are spawned by the main agent, do work, and report results back. Agent teams coordinate through a shared task list, with teammates communicating directly with each other." width="4245" height="1615" data-path="images/subagents-vs-agent-teams-dark.png" />
3232</Frame>
3333 
34| | Subagents | Agent teams |
35| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
36| **Context** | Own context window; results return to the caller | Own context window; fully independent |
37| **Communication** | Return a result to the caller. Subagents that Claude named when it spawned them can also [message each other](/docs/en/sub-agents#what-loads-at-startup) | Teammates message each other directly |
38| **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#task-tool-availability) |
39| **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
40| **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
34| | Subagents | Agent teams |
35| :- | :- | :- |
36| **Context** | Own context window; results return to the caller | Own context window; fully independent |
37| **Communication** | Return a result to the caller. Subagents that Claude named when it spawned them can also [message each other](/docs/en/sub-agents#what-loads-at-startup) | Teammates message each other directly |
38| **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#task-tool-availability) |
39| **Best for** | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
40| **Token cost** | Lower: results summarized back to main context | Higher: each teammate is a separate Claude instance |
4141 
4242Use 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.
4343 
from line 224
224224 
225225An agent team consists of:
226226 
227| Component | Role |
228| :------------ | :---------------------------------------------------------------------- |
227| Component | Role |
228| :- | :- |
229229| **Team lead** | The main Claude Code session that spawns teammates and coordinates work |
230| **Teammates** | Separate Claude Code instances that each work on assigned tasks |
231| **Task list** | Shared list of work items that teammates claim and complete |
232| **Mailbox** | Messaging system for communication between agents |
230| **Teammates** | Separate Claude Code instances that each work on assigned tasks |
231| **Task list** | Shared list of work items that teammates claim and complete |
232| **Mailbox** | Messaging system for communication between agents |
233233 
234234Each 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. Before v2.1.207, a single malformed mailbox entry caused a repeated error every second and blocked delivery for that mailbox until you deleted the file manually.
235235 
Feedback