Claude Code Agent Teams: How They Work and When to Use Them

Claude Code agent teams run several Claude Code sessions at once, with one lead and a group of teammates who share a task list and message each other. They're experimental and off by default. To turn them on, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, then ask Claude in plain English to spawn the team you want.

Use them for work that splits cleanly into parallel pieces. For most everyday tasks, a single session or subagents will be cheaper and simpler.

Details below were checked against Anthropic's agent teams docs on November 5, 2026. This feature is changing quickly, so check the docs before relying on it.

What are Claude Code agent teams?

An agent team is a group of full Claude Code sessions working on one job. One session is the lead. It creates tasks, assigns work and pulls the results together. The teammates each have their own context window, claim tasks from a shared list, and can talk to each other directly.

That last part is what makes a team different. Teammates can challenge each other's findings without everything passing through you.

Agent teams vs subagents

Subagents work inside one session and report back. Agent teams are separate sessions that coordinate themselves. The simple test: if the workers only need to hand back a result, use subagents. If they need to discuss it, use a team.

There's a third option for parallel work: run your own sessions in separate git worktrees. You do the coordinating, but you also keep full control.

How to enable agent teams

Add this to your settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

You can also set the same variable in your shell. Teammates need an interactive session, so they won't spawn in headless mode with the -p flag.

How to start your first team

Describe the task and the teammates you want. Anthropic's own example works well because each role can work without waiting for the others:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

Claude creates the team and the task list. Teammates appear in a panel below your prompt. Use the up and down arrows to select one, press Enter to read its work and message it, and press Escape to clear the selection.

Claude sometimes uses subagents instead of creating a team, and they appear in the same panel. If you specifically want a team, say so in your prompt.

You can also choose the size and model:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

When should you use agent teams?

Agent teams work best when the pieces can run independently. Anthropic lists four strong use cases:

• Research and review: teammates look at different parts of a problem, then challenge each other's findings.
• New modules or features: each teammate owns a separate piece.
• Debugging with competing theories: teammates test different explanations at the same time.
• Cross-layer changes: frontend, backend and tests each have an owner.

Skip them for step-by-step work, edits to the same file, or tasks with lots of dependencies. A single session is better there, because the team would spend its time waiting and colliding.

Best practices

• Start with 3 to 5 teammates. Anthropic suggests this for most workflows, and about 5 to 6 tasks per teammate keeps everyone busy.
• Start with research or review. It's lower risk than having several agents change code on your first try.
• Give each teammate its own files. Two teammates editing one file can overwrite each other.
• Put context in the prompt. Teammates don't get your conversation history, so say what they need to know.
• Keep an eye on it. Check progress and redirect teammates early, rather than coming back to a big mess.

How much do agent teams cost?

Agent teams use significantly more tokens than a single session. Each teammate has its own context window, so usage rises with every active teammate. A team of four can burn through a plan's limits much faster than one session doing the same job one step at a time.

So use the smallest team that works, and shut teammates down when they finish:

Ask the researcher teammate to shut down

If usage is already a concern, read how much Claude Code costs before you try a big team.

Limitations to know

Agent teams are experimental, and Anthropic lists several limits:

• /resume and /rewind don't bring back in-process teammates.
• Task status can lag, which can block other tasks. Check if the work is really done.
• Shutdown can be slow, because teammates finish their current step first.
• A session has one team, and teammates can't create their own teams.
• The lead can't be changed once the team starts.
• Split-pane mode needs tmux or iTerm2, and isn't supported in the VS Code terminal, Windows Terminal or Ghostty. The default in-process mode works in any terminal.

Should you use agent teams for client work?

Yes, but only on the right jobs. They're a good fit for reviewing a client's codebase from several angles, or building separate parts of a larger tool. For a typical small automation, the extra cost and coordination usually isn't worth it.

Learning when not to use them is part of the skill. The Claude Code for agencies course covers how to plan and ship client builds, and you can compare notes in the Claude Code community.

FAQ

What are agent teams in Claude Code?

They're groups of Claude Code sessions that work together on one job. One lead assigns work, and teammates share a task list and message each other. Each teammate is a full session with its own context window.

How do I enable agent teams in Claude Code?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your settings.json or shell, then ask Claude to spawn a team in plain English. The feature is experimental and off by default.

What's the difference between subagents and agent teams?

Subagents work inside your session and report results back to it. Agent teams are separate sessions that coordinate through a shared task list and message each other directly. Teams suit work that needs discussion, but they cost more.

How many teammates should I use?

Anthropic suggests starting with 3 to 5 for most workflows. More teammates means more tokens and more coordination, and the gains flatten out. If you have 15 independent tasks, 3 teammates is a good starting point.

Do agent teams work on Windows?

The default in-process mode works in any terminal. Split-pane mode needs tmux or iTerm2 and isn't supported in Windows Terminal, so most Windows users should stay with in-process mode.