# 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](https://code.claude.com/docs/en/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](/compare/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](/tools/claude-code). Third-party tools that coordinate several coding-agent sessions from outside the harness include [Ruflo](/tools/ruflo), [Claude Squad](/tools/claude-squad), [Vibe Kanban](/tools/vibe-kanban) and [Container Use](/tools/container-use); [wshobson/agents](/tools/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.

## Related tools

- [Claude Code](https://multiagentguide.top/tools/claude-code.md)
- [Ruflo](https://multiagentguide.top/tools/ruflo.md)
- [Claude Squad](https://multiagentguide.top/tools/claude-squad.md)
- [Vibe Kanban](https://multiagentguide.top/tools/vibe-kanban.md)
- [Container Use](https://multiagentguide.top/tools/container-use.md)
- [wshobson/agents](https://multiagentguide.top/tools/wshobson-agents.md)

## FAQ

### Are Claude Code agent teams enabled by default?

No. The official docs describe them as experimental and disabled by default. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in the environment or in settings.json to enable them.

### What is the difference between agent teams and subagents?

Subagents run inside one session and return a result to the caller. Agent teams are separate Claude Code sessions with a lead, a shared task list and direct messaging between teammates. Teams cost more tokens because every teammate is a full instance.

### Can a teammate spawn its own team?

No. The docs list 'no nested teams' as a limitation: only the lead manages the team, and a session has exactly one team.

### Do agent teams work in non-interactive mode?

No. The docs state that with the -p flag, including Agent SDK sessions, Claude does not spawn teammates; a named subagent runs as an ordinary subagent.

### How many teammates should a team have?

The docs suggest starting with 3 to 5 teammates for most workflows and note there is no hard limit, but token cost and coordination overhead grow with team size.

## Sources

- [Claude Code docs: Orchestrate teams of Claude Code sessions](https://code.claude.com/docs/en/agent-teams)
- [Claude Code docs: Create custom subagents](https://code.claude.com/docs/en/sub-agents)

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/topics/agent-teams