A subagent does its job and hands back a report. An agent in a workflow does the same for a script. Neither one ever talks to another agent. Claude Code agent teams work differently: several Claude Code sessions run side by side, send each other findings, question each other's claims, and share one task list, while you can step into any of them. The feature is experimental and off by default, so this post covers how to turn it on, how to start a team that works well, and how to stay in control of it.
What an agent team is
An agent team is one lead session and a few teammates. The lead is the session you start and type into. It starts the teammates, gives each one a job, and combines their results into one answer at the end.
Each teammate is a full Claude Code session with its own context window. It loads the project's context, such as CLAUDE.md, like any session, but it doesn't see the lead's conversation. All it knows about the job is what the lead writes for it when it starts it.
Two things connect the team:
- Messages. Any teammate can message any other by name, without going through the lead, and you can talk to any teammate directly.
- A shared task list. The lead creates tasks, teammates claim them and mark them done, and a task can depend on other tasks, in which case it waits until they are finished.
Compared with the other ways to run several agents: subagents report back to the session that started them, a dynamic workflow follows a script, and a team talks among itself.
When a team is worth it
A team costs more than any other option, because every teammate is a separate Claude instance. It pays off in two situations.
The first is work where findings should be challenged: a review, research, or a bug with several possible causes. A single reviewer tends to settle on the first plausible explanation and stop. In our test runs, three reviewers with different jobs withdrew claims after another teammate disproved them, and the lead held back one finding until a teammate had reproduced it. The documentation recommends starting with research and review for the same reason.
The second is separate pieces of work in separate files, such as a module each, or the code and its tests. Teammates all work in the same folder, so two teammates editing the same file overwrite each other.
For work that runs in sequence or keeps touching the same files, a single session or subagents are the better and cheaper choice.
Turn agent teams on
Agent teams are turned on with an environment variable, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, set to 1. The simplest place is the env block of the project's .claude/settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
"CLAUDE_CODE_ENABLE_TODO_TOOLS": "1"
}
}
The second variable is there for the shared task list. The list is built on Claude's task-tracking tools, and Claude Code provides those by default only on Opus 4.7, Sonnet 4.6, Haiku 4.5, and earlier models. Newer models keep track of their work without a written list, so the tools are left out unless you opt in with CLAUDE_CODE_ENABLE_TODO_TOOLS. Without them a team still works, but the teammates coordinate by messages only and there is no list to watch. We tried both, and for a team the list is worth having.
Two things change once teams are on:
- Claude may start teammates on its own. Claude sometimes names a subagent so it can message it later, and while teams are on, a named subagent launches as a teammate. To get plain subagents back, set the first variable to
0. - Teams need an interactive session. With
claude -p, Claude doesn't start teammates, even with the variable set.
Start a team with a prompt
There is no command that starts a team. You describe the team in a prompt: who is on it and what each one does. This is a shortened version of the prompt from our test runs, a review of a small Python project:
Create an agent team to review rule_audit/ with three teammates named correctness, tests, and readability: one looks for bugs, one checks how well the existing tests cover the commands, and one looks at readability and design. Put the work on the shared task list: one review task per teammate, plus a summary task that depends on all three. Have the teammates claim their tasks and mark them done. Have them share findings and challenge each other, then give me one summary. Don't change any files.
Four things in it matter:
- Names. A named teammate is easy to refer to later, for you and for the other teammates.
- One job each. Clear, separate jobs keep teammates from covering the same ground. Put the details in the prompt, because teammates don't see the lead's conversation.
- The task list, asked for in so many words. In our runs, a lead that wasn't asked coordinated by messages only and never created a task.
- A task that waits. The summary depends on the three reviews, so it stays blocked until they are done.
For the size of a team, the documentation suggests three to five teammates for most work. More teammates mean more tokens and more coordination, and three focused teammates often do better than five scattered ones.
Claude sometimes uses subagents even when you wanted a team, and they appear in the same panel. If that happens, ask again and say "agent team" explicitly.
Follow the work on the task list
Press Ctrl+T in the lead's view to show the task list, and again to hide it. Each task is pending, in progress, or completed, and a blocked task shows which tasks it is waiting for.

In our runs, the lead created the three review tasks and the summary task, each teammate claimed its review and marked it completed, and the summary unblocked on its own when the third review was done. A teammate that finishes early can also pick up the next free task without being told.
Talk to a teammate
The teammates run in the background, and the lead's terminal lists them in the agent panel below the prompt.

From the panel, you work with one teammate at a time:
- Up and Down select a teammate, and Enter opens it. You see its session: what it read, what it ran, what it found.
- What you type there goes straight to that teammate, word for word. That is how you redirect one teammate without touching the others.
- x stops the selected teammate.
- To get back to the lead, select the main row and press Enter.
One warning from our tests: Esc in a teammate's view doesn't take you back. It interrupts that teammate's current turn, and it also cleared the message we had started typing.
You can also reach a teammate from the lead's prompt. Type @, the teammate's name, and your message, for example "@tests which of the bugs found so far has no test?". The difference is that Claude writes the message it sends, so it may reword what you said. For a quick nudge that is fine. For an exact instruction, use the panel.
A teammate that has finished keeps its row while others are still working. Once everyone is idle, the rows hide after 30 seconds, but the teammates are still running, and a message to one of them brings its row back. Permission prompts from teammates appear in the lead's session, and teammates start in the lead's permission mode.
Shut the team down
When the work is done, tell the lead in plain words: "Ask all teammates to shut down." The lead sends each teammate a shutdown request. A teammate finishes its current request or command first, and it can even decline and explain why, so the teammates leave one by one and it takes a while. Until they are gone, they keep running and keep using tokens.
In our runs, the teammates also kept sending idle notices and repeated reports after the summary, and the lead answered each one. Once you have the summary and the task list shows everything completed, shut the team down.
Limits and cost
Agent teams are experimental, and the documentation lists known limitations. These are the ones you will notice first:
/resumeand/rewinddon't bring teammates back. If the lead then tries to message teammates that no longer exist, tell it to start new ones.- A session has one team, and only the lead manages it. Teammates can't start teams of their own.
- Task status can lag. A teammate sometimes doesn't mark a task completed, and a task that depends on it stays blocked. Check whether the work is done, and tell the lead to nudge the teammate.
- Split panes, with every teammate visible in its own pane, need tmux or iTerm2. They aren't supported in the VS Code terminal, Windows Terminal, or Ghostty. The default in-process mode, described in this post, works in any terminal.
On cost: each teammate has its own context window, so usage grows with every teammate and with how long each one runs. In our runs, the team of three reviewers worked for three to five minutes and used about 5% of a Pro plan session. To keep it down, use Sonnet for teammates, keep the team small and the jobs focused, and shut teammates down when their work is done.
Conclusion
Claude Code agent teams are for work that gets better when agents talk to each other: reviews, research, and separate pieces of work in separate files. Turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, add CLAUDE_CODE_ENABLE_TODO_TOOLS for the task list, and describe the team in your prompt: named teammates, one job each, and the work on the shared task list. Watch the list with Ctrl+T, redirect a teammate from the agent panel, and shut the team down when you have the summary.
Relevant Training
Agent teams are covered in Supervising Claude Code Agents, part of Cybrec's Claude AI training program, together with goals, steering and rewinding a running agent, and dynamic workflows.


0 Comments