1. Overview
What Are Agent Teams?
Agent teams enable multiple Claude instances to work in parallel on different subtasks while coordinating through a git-based system. Unlike manual multi-instance workflows where you orchestrate separate Claude sessions yourself, agent teams provide built-in coordination where agents claim tasks, merge changes continuously, and resolve conflicts automatically.
Key characteristics:
- ✅ Autonomous coordination: team lead delegates, teammates communicate via mailbox
- ✅ Peer-to-peer messaging: direct communication between agents (not just hierarchical)
- ✅ Git-based locking: agents claim tasks by writing to shared directory
- ✅ Continuous merge: changes pulled/pushed without manual intervention
- ✅ Independent context: each agent has own 1M token context window (isolated)
- ⚠️ Experimental: research preview, stability not guaranteed
- ⚠️ Token-intensive: multiple simultaneous model calls means high cost
Not the same as cross-session messaging: the mailbox above connects teammates a team lead spawned itself. To message a session that already exists independently, one you started and steer yourself, see Cross-Session Messaging instead. Both use the same underlying
SendMessagetool.
When Introduced
Version: v2.1.32 (2026-02-05) Model: Opus 5 required (Opus 4.6+ compatible) Status: Research preview (experimental feature flag required)
Official announcement:
"We've introduced agent teams in Claude Code as a research preview. You can now spin up multiple agents that work in parallel as a team and coordinate autonomously on shared codebases." Source: Anthropic, Introducing Claude Opus 4.6
📝 Documentation Update (2026-02-09): Architecture section corrected based on Addy Osmani's research. Key clarification: Agents communicate via peer-to-peer messaging through a mailbox system, not only through team lead synthesis. Context windows remain isolated (1M tokens per agent), but explicit messaging enables direct coordination between teammates.
Agent Teams vs Other Patterns
| Pattern | Coordination | Setup | Best For |
|---|---|---|---|
| Agent Teams | Automatic (built-in) | Experimental flag | Complex read-heavy tasks requiring coordination |
| Multi-Instance | Manual (human orchestration) | Multiple terminals | Independent parallel tasks, no coordination needed |
| Dual-Instance | Manual (human oversight) | 2 terminals | Quality assurance, plan-execute separation |
| Task Tool | Automatic (sub-agents) | Native feature | Single-agent task delegation, sequential work |
Key distinction:
- Multi-Instance = You manage coordination (separate projects, no shared state)
- Agent Teams = Claude manages coordination (shared codebase, git-based communication)