Claude Code Agent Teams Still Experimental After 56 Fixes

The costly mistake with Claude Code agent teams is flipping the flag on and leaving it on. Once it's set, Claude can turn an ordinary helper into a full teammate without asking you, and every teammate is a separate Claude session that bills on its own. Turn teams on for one job that needs people arguing in parallel, then turn them off again. For everything else, a plain subagent is cheaper and does the same work.

Agent teams let one Claude Code session act as a lead while other sessions work beside it, share a task list and message each other. The feature shipped in February 2026 and is still marked experimental in November. Every figure below links to where it came from.

Inside This Post

7 sections

What an Agent Team Actually Is

Anthropic's agent teams page describes four parts. A team lead, which is the session you started. Teammates, which are separate Claude Code instances, each with its own context window. A shared task list the teammates claim work from. And a mailbox, so any agent can message any other by name.

That last part is the whole difference from subagents. A subagent does its job and hands a result back to the caller. Teammates can talk to each other, challenge each other's findings and pick up the next open task on their own. You can also message any teammate directly without going through the lead.

Teams and tasks live on your machine, not in your repo. The team config sits under ~/.claude/teams/ and is deleted when the session ends. The task list sits under ~/.claude/tasks/ and stays on disk. A .claude/teams file in your project is just a file, the docs say. Claude Code doesn't read it as config.

How to Turn On Agent Teams in 2026

1. Update first. Run claude --version. Teams arrived in v2.1.32 on February 5, 2026, per the changelog. Many fixes landed much later, so run the newest build you can.
2. Set the flag. Add CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS with the value 1 under env in your settings.json, or export it in your shell.
3. Ask for a team in plain words. Name the roles and what each one owns. "Spawn three teammates to review this PR, one on security, one on performance, one on tests" works well because the roles don't wait on each other.
4. Name the model. Say "use Sonnet for each teammate" in the prompt. Otherwise teammates run on the lead's model, which is often the expensive one.
5. Watch the agent panel. Teammates show up under the prompt. Use the up and down arrows to pick one, Enter to open it, and Ctrl+T to show the task list.
6. Shut them down. Tell the lead to ask a teammate by name to shut down. An idle teammate is still a running session.

If Claude spawns subagents instead of a team, the docs say to ask again and request an agent team by name. The agent panel shows both kinds, so a list of helpers there doesn't prove a team formed.

Split Panes or One Terminal

The default display is in-process. Every teammate runs inside your main terminal and you switch between them in the panel. Split panes give each teammate its own pane, but they need tmux or iTerm2 with the it2 command line tool.

The settings reference lists four values for teammateMode. They are in-process, auto, tmux and iterm2, and the default is in-process. You can also pass --teammate-mode for one session. Split panes don't work in VS Code's built-in terminal, Windows Terminal or Ghostty.

What Agent Teams Cost

There's no separate price for teams. You pay the way you already pay for Claude Code, on a subscription's usage limits or per token on the API. Our Claude Code pricing guide covers those plans.

What changes is how much you burn. Anthropic's cost docs say token use is roughly proportional to team size. The same page says a team uses about 7x the tokens of a standard session when teammates run in plan mode. Four habits from that page keep it down.

One more cost trap sits in the agent teams page. An in-process teammate's prompt cache lasts five minutes by default, even on a subscription. A teammate that waits longer than that pays to rebuild its cache. Setting subagentPromptCacheTtl to 1h keeps it for an hour, but the API bills those one-hour cache writes at a higher rate.

The docs suggest 3 to 5 teammates for most work, with 5 to 6 tasks each. They also say three focused teammates often beat five scattered ones. Past that, you're paying for coordination, not progress.

The Side Effects Nobody Mentions

Your Subagents Can Become Teammates

This is the surprise that costs people money. Per the subagents docs, Claude can give a subagent a name on its own so it can message it later. With teams on, a named subagent in an interactive session launches as a teammate. Claude Code doesn't ask you to confirm the launch.

It gets worse for anyone who isolates helpers in git worktrees. An isolation value in a subagent's file doesn't stop the switch, the same page says, and the teammate then runs in the main session's folder. Two teammates editing one file overwrite each other. If you want plain subagents back, set the variable to 0. The change applies to the running session as soon as you save.

Permissions Copy Over, With One Exception

Teammates start in the lead's permission mode. If the lead runs with --dangerously-skip-permissions, every teammate does too. The one mode they don't inherit is dontAsk. You can change one teammate's mode after it spawns, but not at spawn time.

Plan approval is looser than most people expect. When the lead is in plan mode and spawns a teammate, that teammate plans first. The docs say Claude Code then approves the plan as soon as it arrives, without the lead reviewing it. Edits still go through normal permission prompts. Our test of plan mode on a single session covers what planning costs before teams multiply it.

The Changelog Says It's Still Settling

We read every line of the Claude Code changelog from v2.1.32 on February 5 to v2.1.317 on November 3, 2026. We kept each line that mentions agent teams or teammates, and dropped four where "teammates" meant people or a different product. That left 69 lines across 231 releases. 56 of them were bug fixes.

The work sped up, not down. September had 12 changes and October had 15. Some fixes matter for anyone on an old build.

• v2.1.224, August. SendMessage used to say a message was sent when the write to the inbox had failed.
• v2.1.251, August. A teammate's final answer sometimes didn't reach the lead.
• v2.1.299, October. A teammate started without a description could keep part of a credential from its prompt in the task description.
• v2.1.317, November 3. Split-pane teammates could start in auto mode when the lead was in manual mode.

That last one shipped the day before this post. If you run teams in tmux or iTerm2, update before you trust their permissions.

Bad Advice We Keep Seeing

"Create the team with TeamCreate." Those tools are gone. The changelog says v2.1.178 removed TeamCreate and TeamDelete in June. Every session with the flag on now has one built-in team, and you spawn teammates straight away.

"Set a default teammate model in /config." That setting was removed in v2.1.234 in August. Claude Code ignores a leftover teammateDefaultModel, the agent teams page says. Name the model in your prompt instead.

"Split panes are the default." A guide that ranks for this search says auto is the default. The settings reference says in-process. If nothing splits, that's why.

"Press Shift+Down to switch teammates." That was the February layout. The current docs use the agent panel, with the up and down arrows and Enter.

"Run a team from a script." Teams need an interactive session. In -p mode, a named helper runs as an ordinary subagent even with the flag on.

"Teams cost about 3x." Anthropic's own figure is about 7x a normal session with teammates in plan mode. Plan for a bill several times one session, not a small bump.

When a Team Beats One Session

Anthropic's docs name four strong cases. Research and review from several angles at once. New modules where each teammate owns separate files. Debugging with competing theories, where teammates try to disprove each other. And changes that span frontend, backend and tests, with one owner each.

The docs are just as clear about where teams lose. Sequential work, edits to the same file and tasks with many dependencies go better in one session or with subagents. The advice for a first try is to start with research or review, a job with no code to write.

Packaging the roles you reuse helps. A subagent file can define a role once, like a security reviewer, and the lead can spawn it as a teammate. Our guide to Claude Code skills covers the same idea for instructions you reuse. Note one catch from the docs. A teammate ignores the skills list in that file and loads skills from your project and user settings instead.

Still Wondering?

What are agent teams in Claude Code?

A way to run several Claude Code sessions together. One session leads, the rest are teammates with their own context, and they share a task list and message each other.

How do I enable agent teams in Claude Code?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, either under env in settings.json or in your shell. Then ask Claude for a team in plain words.

What's the difference between subagents and agent teams?

Subagents report a result back to the session that called them. Teammates can message each other and you directly, and they claim work from a shared task list.

How much do agent teams cost?

Nothing extra on top of your plan, but they use far more of it. Anthropic says a team uses about 7x the tokens of one session when teammates run in plan mode.

Do agent teams work in VS Code?

The in-process mode works in any terminal. Split panes don't work in VS Code's built-in terminal, Windows Terminal or Ghostty.

How many teammates should I use?

Start with 3 to 5. Anthropic's docs say three focused teammates often beat five scattered ones.

Can I resume a session with an agent team?

Not fully. /resume and /rewind don't bring back in-process teammates. Ask the lead to spawn new ones.

How do I turn agent teams off?

Set the variable to 0 in your settings and save. The running session picks it up, and named helpers launch as plain subagents again.

Like this guide? Add Vyebe as a preferred source on Google and see more of our posts when you search.

The Paper Trail

• Claude Code docs, Orchestrate teams of Claude Code sessions, setup, display modes, permissions, plan approval, cache lifetime, team size and limitations, accessed November 2026
• Claude Code docs, Manage costs effectively, agent team token costs and the 7x plan mode figure, accessed November 2026
• Claude Code docs, Create custom subagents, subagent names and when they launch as teammates, accessed November 2026
• Claude Code docs, Settings reference, teammateMode values and default, subagentPromptCacheTtl, accessed November 2026
• Claude Code docs, Settings files and precedence, where settings live and which file wins, accessed November 2026
• Claude Code changelog, v2.1.32 through v2.1.317, accessed November 2026
• Vyebe count of agent team lines in the Claude Code changelog, February 5 to November 3, 2026