Previously in series

Introduction

Claude Code already spawns agents without being asked. Give it two independent questions in one session and it may run them in parallel — subagents handling each, results surfacing in your main context. Most of the time you will not notice it happening, and you cannot do much about it if you want to redirect one mid-flight.

Agent Teams is what you reach for when that invisibility becomes a problem. Here you spell out the roles yourself, and every teammate is a separate session sitting in its own pane where you can watch it work and interrupt it. Anthropic shipped this in early February 2026. One session leads, the others do the work, nobody shares a context window, and they talk to each other through a mailbox rather than reporting up.

So the question this article is really about: when is that worth paying for, given Claude will parallelize plenty of work on its own without any of the ceremony?

Subagents vs. agent teams

If you read the last article, you know what subagents are: helper agents spawned within your session to offload focused work. They run in their own context window, do the work, and return a result — the main session sees the summary, not the intermediate steps. They cannot spawn each other, and they cannot talk to each other.

That last constraint is where subagents hit a wall on certain tasks. If I spawn a backend subagent and a frontend subagent to develop a feature together, neither one knows what the other found unless I relay it. Every piece of inter-agent communication goes through me — or rather, through the main agent's context, where it counts against the window. On a complex task, that bottleneck adds up fast.

Agent teams eliminate it. Teammates are independent sessions that can message each other directly through a shared mailbox. The lead does not have to relay everything. A security reviewer can tell the implementation teammate "I flagged this endpoint, adjust your approach" without ever surfacing that exchange in the lead's context. Teammates also self-claim tasks from the shared list, so the lead does not have to micromanage assignment.

The tradeoff is cost. Each teammate is a full Claude Code instance. A three-teammate team uses roughly three to four times the tokens of a single session doing the same work sequentially. The Anthropic docs put the multiplier around 7x in plan mode. That is not a typo.

The practical rule: use subagents when workers need to deliver results back to a central decision-maker. Use agent teams when workers need to share discoveries mid-task and coordinate directly.

When agent teams actually help

The documentation lists a few patterns, and in my experience they are accurate. The genuinely strong cases are:

Parallel research and review. Multiple teammates explore different facets of a problem simultaneously — say, security, performance, and API design — then challenge each other's conclusions. The back-and-forth between teammates surfaces conflicts that a single sequential review would miss.

Cross-layer features. A feature that touches frontend, backend, and tests in largely independent ways is a natural fit. Each teammate owns one layer. File conflicts are minimal as long as you define boundaries clearly upfront.

Debugging with competing hypotheses. You think the bug is in the database layer. I think it is a caching issue. Spawn two teammates to investigate both in parallel, report findings to each other, and converge faster than either would alone.

What does not benefit from agent teams: anything sequential, anything with heavy file overlap, quick tasks that take less time than spinning up a team, and work where you need tight control over every decision.

Enabling and starting a team

Agent Teams are off by default and require a feature flag. The most reliable place to set it is ~/.claude/settings.json, because a shell environment variable only applies to that terminal session:

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

Once enabled, you describe the team in natural language. Claude figures out the structure:

I'm adding a payment webhook handler. Create an agent team: one teammate on the API layer, one on database schema changes, one writing integration tests. They should coordinate through the task list.

Claude spawns the lead, creates teammates, generates the shared task list at ~/.claude/tasks/{team-name}/, and the sessions start running.

By default the display mode is "auto" — split panes if you are already inside a tmux session, in-process otherwise. In-process mode shows all teammates inside your main terminal; you cycle through them with Shift+Down. Split-pane mode requires tmux or iTerm2 and gives each teammate its own visible pane. I find split-pane mode significantly more useful for active work — watching teammates coordinate in real time makes it easier to spot one going off-course.

To force in-process for a session:

claude --teammate-mode in-process

Or set it permanently in ~/.claude.json:

{ "teammateMode": "in-process" }

Setting your CLAUDE.md for team workflows

Teammates load the project's CLAUDE.md when they spawn, the same way a fresh session does — and the same way custom subagents do. If you have already written project-specific subagent definitions in .claude/agents/, those are available to teammates too; a teammate can invoke your code-reviewer subagent exactly as a solo session would. One thing I found useful on top of that: add a short section that applies specifically to agent team context:

```

Agent team notes

When running as a teammate:
- Check the shared task list before starting any new work
- Message teammates directly if you discover something they need to know
- Claim only tasks in your assigned scope
- Do not modify files outside your assigned directory
```

This gives teammates operating guidance without cluttering the instructions that solo sessions see. Teammates will read it; regular sessions mostly ignore a section that does not apply to them.

Summary

Agent Teams are a real capability, not a demo. When the task has genuinely parallel, loosely-coupled components — parallel code review, cross-layer features, competing-hypothesis debugging — they deliver. When the task is sequential, has heavy file dependencies, or is just not big enough to justify three to four times the token cost, stick with subagents or a single session.

Next in the series: The Full Workflow — how setup, CLAUDE.md, hooks, MCP servers, skills, subagents, and agent teams actually stack together in a working session. Not each piece in isolation, but the decisions you make when they interact.