What makes up an agent team?
Think of it this way: instead of one Claude doing everything, you now have a team lead that delegates work to independent teammates. Each teammate is a full Claude Code session — its own context window, its own tools, its own workspace.
They stay coordinated through two shared resources: a task list (what needs doing) and a mailbox (how they talk to each other).
Where things live on disk
Teams and tasks are stored locally. Team config lives at ~/.claude/teams/{name}/config.json with a members array. Tasks live at ~/.claude/tasks/{name}/. Teammates can read the config to discover other team members.
Subagents or agent teams?
Both let you parallelize work, but they solve different problems. The question to ask: do your workers need to talk to each other?
Subagents are like sending assistants on errands — they go, do the work, and bring back a summary. Agent teams are like a war room — everyone's working simultaneously and can challenge, inform, or redirect each other in real time.
| Subagents | Agent Teams | |
|---|---|---|
| Topology | Star — report back only | Mesh — peer-to-peer |
| Context | Results return to caller | Fully independent windows |
| Coordination | Main agent manages all | Shared task list + self-claim |
| Token cost | Lower | Higher (N separate contexts) |
| Best for | Focused, quick tasks | Complex collaborative work |
How tasks flow through the team
The lead breaks work into tasks and adds them to a shared list. Each task has a state: pending, in progress, or completed. Tasks can depend on other tasks — a blocked task won't become claimable until its dependency finishes.
When a teammate finishes their current work, they look at the list and self-claim the next available task. Claiming uses a file lock to prevent two teammates from grabbing the same work.
Watch the tasks move...
Tasks start in Pending. Teammates claim them (file-locked). Blocked tasks wait. Once a dependency completes, downstream tasks automatically unblock.
How teammates talk to each other
There are three ways agents communicate. The important thing: all delivery is automatic. No one needs to poll for messages. When a teammate sends something, it arrives immediately.
Direct Message
Send a message to one specific teammate. Use this for targeted instructions, follow-up questions, or redirecting someone's approach. It's the most common communication pattern.
Two ways to see your team
You can run all teammates inside your existing terminal, or give each one its own pane. Both work — it's a matter of preference and what your terminal supports.
In-Process Mode (default)
All teammates run inside your terminal. Use Shift+Up/Down to select a teammate, Enter to view their session, Escape to interrupt. Ctrl+T toggles the task list. Works everywhere — no extra setup.
Should you use agent teams?
Agent teams add coordination overhead and use significantly more tokens. They're worth it when parallel exploration adds real value — but for sequential work or same-file edits, a single session is faster and cheaper.
Walk through this decision tree. Hover each node for a best-practice tip.
Quick rules
- Strong fit: Research, code review, debugging with competing hypotheses, cross-layer changes
- Moderate: New modules where each teammate owns separate files
- Avoid: Sequential tasks, same-file edits, heavy inter-task dependencies
Where teams really shine
These are the scenarios where agent teams deliver the most value. Each card shows the communication pattern — watch how data flows differently depending on the task type.
Where this comes from
This visual guide is an educational companion to Anthropic's official Claude Code documentation. All technical content, architecture details, and feature descriptions are sourced directly from the docs below. The goal is to make the concepts easier to grasp through interactive visuals — not to replace the original material.
If you're looking for the full, authoritative reference, always start with the official docs.
Primary source
Related documentation
- Subagents — lightweight delegation for focused tasks within a single session
- Permissions — how permission settings apply to teammates
- Settings — enabling experimental features and configuring teammateMode
- Costs — token usage guidance for agent teams
- Common Workflows — git worktrees for manual parallel sessions