Claude Code Agent Teams: Setup, tmux Split Panes, and When to Use Them
Claude Code agent teams: several Claude sessions sharing a task list and messaging each other. Setup, tmux split panes, agent teams vs subagents, and cost.
Agent teams let one Claude Code session (the lead) spawn several other full Claude Code sessions (teammates) that work in parallel, share a task list, and message each other directly. They're still experimental and off by default: you turn them on by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Compared with subagents, which do a job and report back to the main session, teammates coordinate among themselves, which makes them better for research, review and debugging with several angles, and more expensive.
This reflects Anthropic's agent teams documentation as of November 2026. The feature is experimental, so check the docs before relying on specifics.
What an agent team is
A team has four parts, per the docs:
| Part | What it does |
|---|---|
| Team lead | Your main Claude Code session. It spawns teammates and coordinates. |
| Teammates | Separate Claude Code instances, each with its own context window. |
| Task list | Shared work items that teammates claim and complete. |
| Mailbox | Messages between agents. |
Each teammate loads the same project context a normal session does (your CLAUDE.md, MCP servers and skills) plus the spawn prompt the lead writes for it. It does not get the lead's conversation history. Tasks can depend on other tasks; a blocked task waits until its dependencies are done, and teammates pick up the next unblocked task on their own when they finish one.
You can talk to any teammate directly, without going through the lead.
Agent teams vs subagents
Both run work in separate context windows. The difference is who coordinates.
| Subagents | Agent teams | |
|---|---|---|
| Reporting | Return a result to the main session | Message each other and the lead directly |
| Coordination | Main agent manages everything | Shared task list plus messages |
| Best for | Focused jobs where only the answer matters | Work that needs discussion and challenge |
| Token cost | Lower: only a summary comes back | Higher: each teammate is a full Claude instance |
A good rule from the docs: use subagents for quick, focused workers that report back. Use a team when the workers need to share findings, argue, and divide work among themselves.
If you just want several independent sessions on separate branches with no coordination, you don't need either. Run them yourself in git worktrees.
How to enable agent teams
Set the environment variable to 1, either in your shell or in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Put that in ~/.claude/settings.json for all projects, or .claude/settings.json for one.
Two things to know before you turn it on:
- It changes ordinary delegation. When agent teams are enabled and Claude gives a subagent a name, that subagent launches as a teammate. Claude sometimes names subagents on its own, so a team can form even when you didn't ask for one. If you only wanted subagents, set the variable back to
0. - It needs an interactive session. With
claude -p(headless mode) or the Agent SDK, Claude doesn't spawn teammates.
Starting a team
There's no special command. Describe the task and the team in plain language:
Review PR #142 with three teammates: one on security, one on
performance, one on test coverage. Have each report findings,
then summarise.
Claude creates tasks, spawns the teammates, and synthesizes their results. If it uses subagents instead, ask again and say "agent team" explicitly.
You can name the model per teammate ("use Sonnet for each teammate"), and you can reuse a subagent definition from .claude/agents/ as a teammate role: "Spawn a teammate using the security-reviewer agent type."
To end one, ask by name: "Ask the researcher teammate to shut down." There's no separate cleanup step: the team config under ~/.claude/teams/ is removed when the session ends, while the task list under ~/.claude/tasks/ stays on disk for a while.
Display modes: in-process and tmux split panes
There are two ways to see your team.
In-process (default)
All teammates run inside your main terminal. They appear in an agent panel below the prompt:
- Up/Down to select a teammate
- Enter to open its transcript and message it
- Escape to clear the selection (or interrupt the teammate whose transcript you're viewing)
- x to stop the selected teammate
- Ctrl+T to toggle the task list
This works in any terminal with no setup.
Split panes (tmux or iTerm2)
Each teammate gets its own pane, so you can watch everyone at once and click into any pane to interact. This needs tmux, or iTerm2 with the it2 CLI and its Python API enabled.
Turn it on with the teammateMode setting in ~/.claude/settings.json:
{
"teammateMode": "auto"
}
With "auto", teammates open in split panes when you run claude inside tmux or iTerm2, and in-process everywhere else. So the usual setup is:
tmux new -s team
claude
Then ask for teammates. Other values:
"tmux": use tmux even when you launched Claude outside it. Panes open in a separate tmux session; Claude Code shows aView teammatesline with the command to attach from a second terminal."iterm2": use iTerm2's native panes.
For one session only, there's a flag, claude --teammate-mode auto, which the docs mark as experimental and hidden from claude --help.
The docs also note that tmux "traditionally works best on macOS" and has known limitations on some systems, and suggest tmux -CC inside iTerm2 as the smoothest entry point. If a team's tmux session outlives Claude Code, clean it up with tmux ls and tmux kill-session -t <name>. New to tmux? See tmux for long-running sessions.
Permissions
Teammates start in the lead's permission mode. That includes bypassPermissions if you started the lead with --dangerously-skip-permissions, so every teammate inherits it. You can't set different modes per teammate at spawn time, though you can switch a running teammate with Shift+Tab.
Permission prompts from teammates show up in the lead's session. If that gets noisy, pre-approve common safe commands in your settings before you start (permission modes explained).
A teammate can't approve a permission on your behalf. Messages between agents are marked as coming from another Claude session, not from you.
What it costs
This is the main reason not to use teams by default. Each teammate is a separate Claude instance with its own context window, so token use grows roughly in line with the number of active teammates and how long each runs. Anthropic's cost docs put it at approximately 7x the tokens of a standard session when teammates run in plan mode.
The docs' advice for keeping it manageable:
- Use Sonnet for teammates.
- Keep teams small. 3-5 teammates is the suggested starting point; three focused teammates often beat five scattered ones.
- Keep spawn prompts focused, since everything in them is loaded into each teammate's context.
- Shut teammates down when they're done. An idle-but-running teammate is still a session.
On a Pro or Max plan, a team eats into your usage limits faster. On API billing, it shows up directly on the bill. See keeping Claude Code costs down.
When to use a team (and when not to)
The docs name four strong cases:
- Research and review: several reviewers each apply a different lens to the same PR or design.
- New modules or features: teammates each own a separate piece.
- Debugging with competing hypotheses: teammates investigate different theories and try to disprove each other's. A single agent tends to find one plausible explanation and stop.
- Cross-layer changes: frontend, backend and tests, each owned by a different teammate.
Skip teams for sequential work, changes to the same file (two teammates editing one file overwrite each other), and anything with lots of dependencies between steps. A single session or a subagent is cheaper and simpler there. If you're new to teams, the docs suggest starting with review or research, which shows the benefit without the coordination problems of parallel coding.
Current limitations
Because it's experimental, there are rough edges the docs list openly:
/resumeand/rewinddon't bring back in-process teammates; tell the lead to spawn new ones.- Teammates sometimes don't mark tasks complete, which blocks dependent tasks.
- Shutdown can be slow, since teammates finish their current step first.
- One team per session, no nested teams (teammates can't spawn their own), and the lead can't be changed.
- The lead sometimes starts doing the work itself. "Wait for your teammates to complete their tasks before proceeding" fixes it.
EasySpawn runs Claude Code on a persistent cloud server you can reach over SSH, so a tmux session with a running team keeps going after you close your laptop. See how it works or join the waitlist.
Related: Claude Code Subagents: When to Split the Work (and When Not To) · Running Claude Code Agents in Parallel With Git Worktrees · A tmux Cheat Sheet for Long-Running Sessions (and AI Agents) · Claude Code Permission Modes Explained: Manual, Accept Edits, Plan, and Auto
Keep reading
MCP Transports: stdio vs Streamable HTTP (and What the 2026 Spec Changed)
MCP servers talk to clients over stdio (a local subprocess) or Streamable HTTP (a remote endpoint). How each works, when to choose which, how to add both to Claude Code, why the old HTTP+SSE transport is deprecated, and what the stateless 2026-07-28 specification means for building and hosting HTTP servers.
Claude Code Routines: Scheduled, API and GitHub-Triggered Agents in the Cloud
Routines are saved Claude Code tasks — a prompt, repositories and connectors — that run on Anthropic's cloud or an organization's self-hosted environment. How to create one with /schedule or the web, use schedule, API and GitHub triggers, and manage limits and security.