Agent Teams — Architecture and Communication
Agent teams are independent Claude Code sessions that communicate peer-to-peer through a shared task list. Unlike subagents that report back to a caller, teammates coordinate directly — making them the right tool for work that requires handoffs, sequential dependencies, or parallel specialization.
Quick Reference
- →Agent teams are still experimental as of April 2026 — requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
- →Requires Claude Code v2.1.32 or later
- →Team Lead spawns teammates; teammates are independent sessions with their own context windows
- →Shared Task List is the only shared state — agents pull tasks, mark in-progress, mark complete
- →Teammates load CLAUDE.md and MCPs but NOT the lead's conversation history
- →No session resumption: disconnect = team gone, spawn new teammates after resuming
- →Use /ultraplan (v2.1.101+) for collaborative plan refinement before spawning the team
- →Agent teams beat subagents when agents need to wait on each other or build on each other's work
Agent Teams vs Subagents — When to Use Each
The fundamental difference: a subagent reports back to the caller. An agent team is a group of independent sessions that coordinate with each other. Subagents are hierarchical — one agent delegates to another and gets a result. Agent teams are peer-to-peer — teammates communicate directly and build on each other's work.
| Situation | Use Subagents | Use Agent Teams |
|---|---|---|
| Task has clear delegation structure | Yes — lead delegates, subagent returns result | Overkill |
| Tasks are truly independent | Yes — /batch is even better | Unnecessary overhead |
| Tasks have sequential dependencies | Awkward | Yes — Shared Task List manages handoffs |
| Agents need to communicate while working | Not possible | Yes — peer messaging and task state |
| One agent needs to wait on another | Not possible | Yes — polling task state handles waits |
| Work requires multiple specialists building on each other | Awkward | Yes — natural fit |
Agent teams shipped with Opus 4.6 in February 2026 and remain experimental as of April 2026. The CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 flag is still required. Known limitations: no session resumption, occasional task lag, slow shutdown.