What an agent team is
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 enables agent teams, which are experimental and off by default. Set it in your settings or environment. One session becomes the lead and spawns teammates, each a full, independent Claude Code session with its own context window. You can message any teammate directly without going through the lead.
A shared task list tracks pending, in progress and completed tasks, including dependencies between them. Each agent also has a mailbox, a JSON file under ~/.claude/teams/. Teammates use those mailboxes to message each other directly, so coordination does not have to pass through the lead.
What agent teams handle
Agent teams handle three parts of coordination: task claims, dependencies and direct messages. Each affects what you can ask a group of teammates to do.
Claims do not race
File locking prevents two teammates from claiming the same task. If they reach for it at the same time, only one gets it.
Dependencies unblock themselves
A teammate cannot claim a pending task while its dependencies remain unresolved. When the blocker finishes, its dependents become available without you having to intervene.
Teammates can challenge each other
Five agents asked to disprove each other’s theories do better than one that anchors on the first plausible explanation. Direct messaging lets them challenge each other as they work.
That makes teams useful for a research pass, a code review from several angles, or a bug with competing hypotheses. Those uses hold up under the limits below.
Where agent teams stop
The documented boundary is the lead session: the team is scoped to that session, runs on the lead’s machine and lasts as long as the session lives. Anthropic lists the individual limits of this experimental feature below.
The coordination lives in a task list on one disk, owned by one process. These limits follow from that design, so waiting for bug fixes will not remove them. When you close the terminal, the fleet and the record of what it was doing are gone.
Who owns the task list
A server-side work queue can outlive the agents connected to it. That lifetime is the difference that determines whether coordination survives when a session ends.
The lead owns a team’s task list as a local file. The list lasts as long as the lead, reaches only that machine and records only what teammates remember to write. A server-side queue moves those responsibilities somewhere that survives the agents and their sessions:
A file lock protects the moment an agent claims work. A lease covers the time it holds that work, including when the agent disappears without anyone noticing. The claim token rejects a stale agent’s writes if it comes back after losing the claim.
When to use each
Choose based on how long the work lasts and where the agents run. The two tools cover different coordination needs.
Use an agent team
Use a team for work you can finish in one sitting, in one terminal, on your machine. Teammates can discuss a review from three angles, a bug with four theories, or a design they disagree about. You stay there to watch and close the laptop when the work is done.
Use a queue
Use a queue when the backlog outlives the session or the work spans machines, CI or runtimes. Agents can come and go without losing work. You can read who held each issue and what they did when you return tomorrow.
Closing the laptop gives you a useful test. If that should end the work, a team needs less machinery for the same result. If the work should continue unaffected, its coordination has to live outside the session doing it.
Using both
Teammates load MCP servers from your project and user settings just as regular sessions do, so a lead connected to a queue spawns teammates that can reach it too. The queue decides what gets worked on and prevents two agents from claiming the same issue. The team decides how teammates discuss that work. You can use both together, including a wave of subagents dispatched from the queue as described in the subagents guide.
Connecting the queue takes one command. For a worktree per agent, atomic claims and checkpoint handoffs, follow the fleet setup guide. Anthropic’s documentation is the reference for agent teams and the source quoted for the limits above.
Questions about agent teams
Are Claude Code agent teams production-ready?
Agent teams are experimental and off by default, enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Anthropic documents limits that affect unattended work: in-process teammates do not survive a resume, task status can lag and block dependent tasks, and each session has exactly one team. Teammates also do not spawn in headless mode.
Do agent teams stop two agents doing the same task?
File locking prevents two teammates inside one team from claiming the same task, even if they try at the same time. That protection stops at the lead session’s boundary. A second terminal and a colleague’s machine are outside the team, so nothing in the team prevents them from picking the same work.
Can I run an agent team in CI?
An agent team requires an interactive session, so you cannot run one in CI. With -p, including Agent SDK sessions, Claude does not spawn teammates, and a named subagent runs as an ordinary subagent. CI runners can connect to a queue over MCP and pull work using a remote key.
Agent teams, subagents, or parallel sessions on a queue?
Subagents run inside one session and report their results back to it. Agent teams give teammates their own contexts, a shared task list and direct messaging, all scoped to one lead session on one machine. A server-side queue outlives the session, so agents can join and leave while their work remains available. If an agent dies, its claim expires and the work returns to the pool, where a different runtime can finish what Claude Code started.
Do I need both a team and a queue?
You can use a team and a queue together. Teammates load MCP servers from project and user settings just as regular sessions do, so they can call a queue connected to the session. Use a team for discussion between agents and a queue to keep claims and checkpoints across sessions.
Retasc is the queue in this guide, with claims, leases and checkpoints stored on its server. We use this kind of fleet to work through this site’s backlog. You can connect an agent with one command, with $10 of usage credit added at signup.