Claude Code team feature explained

Claude Code can run multiple agents that work together. A single session can already launch subagents that report back to the main agent, but the agent teams feature goes further: it creates separate Claude Code instances that communicate directly. The feature is experimental and disabled by default. When enabled, a team lead coordinates other Claude Code instances working on related tasks. This post explains what agent teams are, how they differ from subagents, how to enable them and where they help.

What agent teams are

In a standard Claude Code session you can launch subagents to handle individual tasks. Subagents run within the same session: they do their work and report results back to the main agent, and they never communicate with each other. Agent teams are different. Teammates are independent Claude Code instances. They share a task list, claim work and communicate directly with one another through a built-in messaging system. Because each teammate has its own context, the team can divide work that a single context window would struggle to hold.

How to enable it

Agent teams require a recent version of Claude Code. Check the official agent teams page for the current minimum, and confirm your version with claude --version. The feature is disabled by default; you enable it by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, either as an environment variable or in settings.json. When you start a session with teams enabled, Claude acts as the team lead. The lead creates a shared task list and spawns teammates as needed. Each teammate works on its share of the tasks, and teammates can message the lead or each other to share findings and coordinate. You can also message an individual teammate directly. The lead monitors progress and presents a combined result.

Because each teammate runs in its own context, teammates can read different files, hold separate state and run commands concurrently. That makes agent teams well suited to work that spans multiple modules or layers of a system, where subagents in a single session would be more constrained.

Who it is for

The documentation describes several use cases: research and review tasks that split across multiple agents, building a new module that touches several layers of a system, debugging with competing hypotheses, and cross-layer coordination such as frontend, backend and tests. Each teammate keeps its own context and can talk to the others, so a complex task can be divided and conquered.

Strengths

• Parallel execution. Multiple Claude Code instances work in parallel on different parts of a task, which can reduce overall completion time.
• Shared coordination. Teammates each keep their own independent context window but share a task list and a messaging system, so a discovery by one teammate can inform the others.
• Division of labour. The lead assigns work across teammates and assembles the result.

Limitations

The feature is experimental, and the documentation lists concrete limitations to plan around:

• One team at a time. You can run a single team per session.
• No nested teams. Teammates cannot spawn their own teams or teammates.
• No session resumption with in-process teammates. Resuming or rewinding a session does not restore teammates that were running in that session.
• Operational rough edges. Task status can lag behind the actual state, shutting a team down can be slow, the lead role is fixed once set, permissions are set when a teammate is spawned, and split-pane views require tmux or iTerm2.

Teams also add cost. Each teammate consumes tokens and runs as its own session, so the total spend is higher than a single session. For simple or linear tasks, subagents or one session are usually enough.

When to use agent teams

Use agent teams when work can be naturally divided and you want to reduce turnaround time. Good examples include investigating different components of a bug at once, developing a feature that spans backend, frontend and infrastructure, reviewing a large change by splitting files across teammates, and running competing design hypotheses in parallel. If your task is sequential, isolated to a single file or small in scope, a single session or subagents will usually be more efficient. Whatever you choose, monitor each teammate's output and integrate the work carefully to avoid conflicts.