A second way to run multiple Claude Code sessions at once
Claude Code has offered subagents for a while: a way to delegate a focused piece of work to a helper agent that reports its result back to the main session and disappears. Agent teams, an experimental feature documented at code.claude.com/docs/en/agent-teams, is a different shape of the same idea. Instead of one agent farming out isolated errands, one session becomes a team lead that coordinates several teammates, each a fully independent Claude Code instance with its own context window, working through a shared task list and messaging each other directly.
It's still marked experimental and disabled by default, so this is a feature worth understanding before you flip it on, not one to assume is already running in a normal session.
Enabling it
Agent teams require the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable set to 1, either directly in your shell or through settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Without it, Claude Code sets up no team directories at session start and never proposes or spawns a teammate, whatever you ask. With it on, describing a task with independent angles is usually enough to get a team going:
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 decides how many teammates to spawn and how to divide the work, or you can be explicit: "spawn 4 teammates to refactor these modules in parallel, use Sonnet for each." One important side effect of turning this on: Claude sometimes names an ordinary subagent so it can be messaged later, and with agent teams enabled, any named subagent spawn launches as a teammate instead, even when you never explicitly asked for a team. If you want plain subagents back, set the variable to 0 again.
How teammates actually coordinate
Two mechanisms do the coordination work, and understanding both is most of what you need to use the feature well.
The shared task list
The lead breaks work into tasks, each in one of three states: pending, in progress, or completed. Tasks can depend on other tasks, and a pending task with unresolved dependencies can't be claimed until those clear, which Claude Code manages automatically once the blocking task completes. Teammates either get assigned a task explicitly by the lead, or self-claim the next unblocked task once they finish their current one. Claiming uses file locking, so two teammates racing for the same task can't both win it.
Direct messaging
Each agent's inbox is a JSON file at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json, and message delivery is automatic: teammates don't need to poll each other, and when a teammate goes idle it notifies the lead on its own. That idle notification doesn't carry the teammate's actual output, though. A teammate shares what it found by sending a message or updating the shared task list, not simply by finishing, so a teammate that stops without reporting anything looks the same to the lead as one that quietly did nothing useful.
You can also message a teammate directly yourself. In the default in-process display mode, arrow keys select a teammate in the agent panel and Enter opens its transcript, where anything you type goes straight to that teammate rather than the lead. Split-pane mode, which needs tmux or iTerm2 with the it2 CLI, gives each teammate its own visible pane instead.
Agent teams vs subagents: which to use
| Subagents | Agent teams | |
|---|---|---|
| Context | Own window; result returns to the caller | Own window; fully independent |
| Communication | Reports back to the main agent only | Teammates message each other directly |
| Coordination | Main agent manages everything | Self-coordination plus a shared task list |
| Best for | Focused tasks where only the result matters | Work that benefits from discussion between agents |
| Token cost | Lower | Higher, each teammate is a separate instance |
The clearest signal for which one fits: does the work benefit from teammates actually talking to each other? Anthropic's own strongest use cases bear this out directly:
- Debugging with competing hypotheses. Several teammates investigate different theories and are explicitly told to try to disprove each other, which counters the anchoring a single investigator falls into once it's explored one plausible explanation.
- Parallel code review. One teammate on security, one on performance, one on test coverage, each applying a different lens to the same pull request simultaneously rather than in sequence.
- New modules or features, where teammates can each own a separate piece without stepping on each other's files.
None of that requires a team if the work doesn't actually benefit from cross-talk. Sequential tasks, edits that touch the same files, or work with heavy dependencies between steps are still better served by a single session, or by ordinary subagents that just need to report a result.
What it costs
Agent teams use noticeably more tokens than a single session, since every teammate keeps its own context window running independently and none of that gets shared or summarised until a teammate chooses to report it. Coordination overhead grows with team size too: more teammates means more messages, more task claiming, and more chances for two teammates to conflict on the same file. Anthropic's own guidance suggests starting with 3 to 5 teammates for most workflows, and sizing tasks so a teammate produces a clear deliverable (a function, a test file, a review) rather than something too small to be worth the coordination cost or too large to check in on before real time is wasted.
Known limitations
This is still experimental, and Anthropic documents the rough edges plainly rather than glossing over them:
- Resuming a session doesn't bring in-process teammates back.
/resumeand/rewinddon't restore them, so the lead can end up trying to message teammates that no longer exist. The fix is just telling the lead to spawn replacements. - Task status can lag. A teammate that finishes work sometimes fails to mark its task complete, which blocks anything depending on it. Check whether the work is actually done before assuming a stuck task means stalled work.
- Only one team per session, and no nested teams. A session gets exactly one team for its lifetime, and teammates can't spawn teammates of their own; only the lead manages the team.
- Permissions are fixed at spawn. Every teammate starts with the lead's permission mode. You can change an individual teammate's mode after it's running, but not before it spawns.
- Split panes need tmux or iTerm2, and aren't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty. In-process mode works everywhere, but only one teammate's transcript is visible at a time.
Where agent teams fit alongside skills
Teammates load the same project context a regular session would when they spawn: CLAUDE.md, MCP servers, and Agent Skills all come along automatically, plus whatever prompt the lead hands them. One frontmatter detail worth knowing if you're building teammates from a custom subagent definition: the skills and mcpServers fields on that definition aren't applied when it runs as a teammate. A teammate always loads skills and MCP servers from your project and user settings instead, the same as any regular session, regardless of what a subagent definition tries to scope for it.
Troubleshooting
Teammates aren't appearing after you ask for them. Check the agent panel below the prompt input first; a teammate row that's gone quiet may just be hidden, not stopped, since idle rows collapse 30 seconds after the whole panel goes idle and reappear on the teammate's next turn. It's also worth confirming Claude actually judged the task complex enough to warrant a team at all: Claude decides whether to spawn teammates based on what you asked for, and a task that reads as simple may just get a normal reply.
Claude keeps spawning teammates when you wanted plain subagents. This is the side effect of enabling the feature: any subagent Claude names launches as a teammate while CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set. Set it back to 0 in your user settings.json to make named subagents launch as subagents again, though a higher-precedence settings file (project, local, or managed) that also sets the variable to 1 overrides that.
Too many permission prompts land on the lead. Teammate permission requests all bubble up to the lead session rather than prompting wherever the teammate is running, which is by design but can create friction fast with several teammates active at once. Pre-approving common operations in your permission settings before spawning a team cuts down on the interruptions.
Where to go next
For lighter-weight delegation that doesn't need teammates talking to each other, see how Claude Code's subagents work. If you're deciding whether to trust a team of agents to run with fewer prompts in between, Claude Code's auto mode and the Agent Skills security guide cover the permissions side of that decision. For scheduling a team's work to run unattended rather than in front of you, see Claude Code Routines vs /loop. Browse the current catalogue at getclaudeskills.com/platforms/claude-code.
