Agent teams in Claude Code: what they are, how they differ from subagents, when to use them

What agent teams are

Agent teams are a Claude Code feature for running several Claude Code sessions as one coordinated group. One session is the team lead. It spawns teammates, assigns work and combines results. Each teammate is a separate Claude Code instance with its own context window. Teammates can message each other directly, and the user can message any teammate without going through the lead. Source: Claude Code docs: agent teams.

Status: experimental, off by default

The official documentation labels agent teams as experimental and disabled by default. They are enabled by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the environment or in the env block of settings.json. Spawning teammates requires an interactive session: with the -p flag (non-interactive mode, including Agent SDK sessions) Claude does not spawn teammates. The docs also note that enabling the feature changes ordinary delegation: a subagent that Claude names is launched as a teammate, so a team can form without being requested; setting the variable to 0 restores subagent behavior.

Parts of a team

Part	Role (per the official docs)
Team lead	The main session; spawns teammates and coordinates. Fixed for the session's lifetime.
Teammates	Separate Claude Code instances working on assigned tasks.
Task list	Shared list with pending / in progress / completed states and dependencies; claiming uses file locking.
Mailbox	Per-agent JSON inbox under ~/.claude/teams/{team-name}/inboxes/.

Teammates load the same project context as a normal session (CLAUDE.md, MCP servers, skills) plus the spawn prompt. The lead's conversation history is not passed on. Display is either in-process (default, any terminal) or split panes (requires tmux or iTerm2).

Agent teams vs subagents

	Subagents	Agent teams
Scope	Inside one session	Several sessions, one lead
Communication	Result returns to the caller	Teammates message each other directly
Coordination	Main agent manages all work	Shared task list plus messages
Token cost	Lower (results are summarized back)	Higher (each teammate is a full instance)

The docs' rule of thumb: subagents for focused tasks where only the result matters; agent teams when workers need to share findings, challenge each other and coordinate themselves. Full comparison: agent teams vs subagents.

When the docs say to use them

• Research and review where several angles are examined at once.
• New modules or features where each teammate owns separate files.
• Debugging with competing hypotheses.
• Changes across layers (frontend, backend, tests) with one owner each.

When not to use them

The docs state that teams add coordination overhead and use significantly more tokens than a single session, and that sequential tasks, edits to the same file, and work with many dependencies are better served by a single session or subagents. Two teammates editing one file leads to overwrites.

Documented limitations (as of 2026-09-30)

• /resume and /rewind do not restore in-process teammates.
• Task status can lag; a teammate may not mark a task completed, which blocks dependents.
• One team per session; no nested teams; the lead cannot be changed.
• Permission mode is inherited from the lead at spawn; teammate permission prompts appear in the lead session.
• Split-pane mode is not supported in VS Code's integrated terminal, Windows Terminal or Ghostty.
• Suggested starting size is 3 to 5 teammates; token cost scales with the number of active teammates.

Related tools in this directory

Agent teams are built into Claude Code. Third-party tools that coordinate several coding-agent sessions from outside the harness include Ruflo, Claude Squad, Vibe Kanban and Container Use; wshobson/agents is a collection of subagent definitions, which the docs say can also be used as teammate roles. These projects are independent of Anthropic; check each tool page for what it actually does.