What an agent team is
Agent teams are experimental and off by default. You turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings or the environment. Once on, one session becomes the team lead and spawns teammates. Each teammate is a full, independent Claude Code session with its own context window, and you can message any of them directly instead of going through the lead.
Coordination runs on two things. A shared task list, where tasks are pending, in progress or completed and can declare dependencies on each other. And a mailbox per agent, a JSON file under ~/.claude/teams/, so teammates message each other rather than reporting up.
What holds
Three things work, and they are worth naming precisely, because a fair comparison starts with what a tool is genuinely good at.
Claims do not race
Task claiming uses file locking, so two teammates reaching for the same task cannot both win it. Inside a team, the double-take problem is solved.
Dependencies unblock themselves
A pending task with unresolved dependencies cannot be claimed. When a teammate finishes the blocker, the dependents unblock with no action from you.
Teammates argue
They message each other directly. That is the real win: five agents told to disprove each other’s theories beat one agent that anchors on the first plausible one.
If your work is a research pass, a multi-lens code review, or a bug with competing hypotheses, that is the feature, and none of the rest of this page argues otherwise.
Where it stops
Anthropic publishes the limits, which is the honest thing to do with an experimental feature. Read as a set, they describe one boundary: the team is scoped to the lead session, on the lead’s machine, for as long as that session lives.
None of these are bugs to wait out. They follow from where the coordination lives: a task list on one disk, owned by one process. Close the terminal and the fleet is gone, and so is the record of what it was doing.
The line: who owns the task list
The difference between an agent team and a work queue is not a feature list. It is one question. Does the coordinator outlive the agents? Everything else follows from the answer.
A team’s task list is a file the lead owns. Its lifetime is the lead’s lifetime, its reach is that machine, and its truth is whatever the teammates remembered to write down. A server-side queue moves the same three things somewhere that survives all of them:
That last one is the difference a file lock cannot cover. A lock protects the moment of claiming. A lease protects the whole time the work is held, including the part where the holder stopped existing and nobody noticed.
Which one you want
Most of the time this is not close, because the two answer different questions.
Take an agent team
The work fits in one sitting, in one terminal, on your machine. You want teammates that discuss: a review from three angles, a bug with four theories, a design explored by people who disagree. You are there, watching, and you will close the laptop when it is done.
Take a queue
The backlog outlives the session. More than one machine, or CI, or more than one runtime. Agents that come and go without losing work. A record of who held what and what they did, that you can still read tomorrow.
The tell is the laptop. If closing it should end the work, a team is less machinery for the same result. If closing it should change nothing, the coordination cannot live inside the session doing the work.
Using both
They are not exclusive. Teammates load MCP servers from your project and user settings the same way a regular session does, so a lead wired to a queue spawns teammates that can reach the same queue. The division that makes sense is the one each is good at. The queue decides what gets worked and guarantees no two agents take it. The team decides how a piece of it gets argued out.
Wiring the queue half is three commands. The fleet setup, a worktree per agent with atomic claims and checkpoint handoffs, is its own guide. The reference for agent teams themselves is Anthropic’s documentation, and the limits above are quoted from it.
Questions that come up
Are Claude Code agent teams production-ready?
They are experimental and off by default: you enable them with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Anthropic documents the limits, and they are the ones that matter for unattended work: in-process teammates do not survive a resume, task status can lag and block dependent tasks, a session has exactly one team, and no teammates spawn in headless mode.
Do agent teams stop two agents doing the same task?
Inside one team, yes. Task claiming uses file locking, so two teammates racing for the same task cannot both win it. Across teams it does not arise, because a team is scoped to its lead session: a second terminal is not on the team, and neither is a colleague’s machine. Nothing is stopping those two from picking the same work.
Can I run an agent team in CI?
No. Spawning teammates requires an interactive session. In headless mode with -p, including Agent SDK sessions, Claude does not spawn teammates and a named subagent runs as an ordinary subagent instead. A queue an agent connects to over MCP has no such restriction, which is why CI runners can pull from one.
Agent teams, subagents, or parallel sessions on a queue?
Subagents run inside one session and report their result back to it. Agent teams give teammates their own context, a shared task list and direct messaging, scoped to one lead session on one machine. A server-side queue is the one that outlives the session: agents join and leave, a dead agent’s claim expires and its work returns to the pool, and a different runtime can finish what Claude Code started.
Do I need both a team and a queue?
They are not exclusive. Teammates load MCP servers from your project and user settings the same way a regular session does, so a teammate on a session wired to a queue can call the queue itself. Use a team when the coordination is a conversation, and a queue when it is a contract.
Retasc is the queue in this guide: the claims, the leases and the checkpoints live on its server, and this site’s own backlog is worked by exactly this kind of fleet. Connecting an agent takes three commands, and signup seeds the first $10 of usage.