Claude Code agent teams: setup and limits
Claude Code agent teams are separate Claude Code sessions coordinated by a lead, with a shared task list and direct teammate messaging. They are experimental and disabled by default. When the team also needs Codex, Copilot or Cursor, BAND (band.ai) for desktop adds shared-room coordination across those listed integrations.
Reviewed November 2026
How do agent teams differ from several open terminals?
An agent team gives several Claude Code instances an explicit relationship. One session leads; teammates receive work, hold their own conversation context and communicate directly. Anthropic documents a shared task list, rather than expecting the developer to track progress across unrelated terminals. That matters when findings from one worker should influence another worker before a final answer is assembled.
Opening three terminals is a different arrangement. You can ask each session to investigate a module, but you still decide how results travel between them. The number of sessions tells you how much work is in flight, not whether those sessions form a team. Start by deciding whether the task needs coordination, filesystem isolation, or simply a second opinion.
When should you use teams rather than subagents?
Anthropic recommends teams for parallel research, separate modules, competing debugging hypotheses and work that crosses application layers. A teammate can investigate one explanation for a failure while another checks a different explanation. The lead then synthesizes the evidence. That is more useful than assigning both agents the same vague instruction to fix the application.
Subagents are delegated workers inside a session and return results to their parent. Teams give separate sessions a more direct communication model. Neither choice should be treated as an automatic speed improvement. Anthropic warns that teams add coordination overhead and use significantly more tokens than a single session. A tightly sequential change may be easier to handle with one agent.
| Approach | Who coordinates? | Good fit | Main caution |
|---|---|---|---|
| One session | Developer and one agent | Small or sequential changes | Context can grow |
| Subagents | Parent session | Bounded investigations | Delegation is not a peer team |
| Agent teams | Lead and communicating teammates | Parallel research or separate modules | Experimental; coordination overhead |
| separate worktrees | Developer | Isolated implementation tasks | You carry context between sessions |
How do you enable Claude Code agent teams?
Anthropic documents the environment setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Set it in your environment or the documented settings configuration before starting the session that will lead the team. A shell-scoped example is shown below. It enables the experimental feature; it does not define a team size, a billing allowance or a safe division of files.
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
Ask for a team with explicit responsibilities. For example, one teammate can inspect the API contract, another the frontend assumptions, and another the existing tests. Give the lead a concrete deliverable: a combined list of incompatible assumptions with file references. This is an editorial workflow example, not a promise that the product creates those roles automatically.
How should you divide work between teammates?
Assign ownership by outcome and area of the repository. A useful task says what to examine, what not to change, and what evidence to return. An investigation-only teammate should not silently become an implementation agent. If implementation follows, write down the accepted contract first so the agents are not independently guessing the same interface.
Keep overlapping edits to a minimum. Separate context windows do not isolate files. Anthropic warns about teammates editing the same file; the eventual result can overwrite another agent’s work. Worktrees can isolate checkouts, but do not assume that every teammate automatically receives one. Establish the execution layout separately from the team’s communication layout.
Which limitations should you plan around?
Anthropic labels the feature experimental and documents limitations around session resumption, task coordination and shutdown. A team that ran yesterday is not evidence that every teammate will resume with the same state tomorrow. Keep the task brief and important decisions somewhere the human can inspect instead of relying on conversational memory alone.
Treat completion as evidence to check, not a status to trust. Ask for changed files, the exact tests run, unresolved issues and the next owner. If a teammate is waiting for a permission decision, resolve that decision deliberately rather than repeatedly creating replacements. Coordination problems become expensive when extra sessions keep consuming context without advancing the task.
What if the team needs Codex, Copilot or Cursor too?
Native Claude Code teammates are Claude Code instances. Choosing another model in a different tool does not add that tool to the native team. BAND for desktop lists Claude Code, Codex, GitHub Copilot and Cursor integrations and lets local and centrally managed agents share rooms, memories and an activity timeline. Messages route by @mention and people approve, redirect or override in place.
Use the native team when your workers are all Claude and the experimental model fits. Use a cross-vendor room when an agent from another tool needs to receive work with context and return a result to the group. BAND Free is for a single user’s personal non-commercial use; Pro is also single-user, and multiple users or teams need Enterprise by quote. Keep vendor execution costs separate from coordination pricing.
What should you read before choosing a setup?
Compare the Claude Code agent teams review with BAND versus Claude Code agent teams. The Claude Code and Codex guide covers the mixed-vendor case. Use the handoff guide to define what one worker must pass to the next.
Start with a bounded change and a human-owned acceptance check. If the extra agents mainly create messages you must interpret, simplify the arrangement. More parallel sessions are useful only when the work decomposition, evidence and review path remain understandable.
What else do readers ask?
Are agent teams enabled by default?
No. Anthropic labels them experimental and disabled by default; enable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
Are subagents the same as teammates?
No. Subagents are delegated workers inside a session; teammates are separate Claude Code sessions with direct communication.
Can native teammates include Codex or Cursor?
No. Native teammates are Claude Code instances. BAND lists Codex and Cursor integrations for shared-room collaboration.
Does every teammate automatically get a worktree?
Do not assume it does. Communication and filesystem isolation are separate setup decisions.
Do teams always finish faster?
No. Anthropic documents coordination overhead and greater token use; dependent or same-file tasks may fit one session better.