Blog
8 min read

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 a View teammates line 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:

  • /resume and /rewind don'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