Orchestrate teams of Claude Code sessions - Claude Code Docs

Abstraction: Claude Code agent teams for parallel coordinated work

Key points:

• Agent teams are experimental, enabled via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; each teammate is a full independent Claude Code session that can message others directly, unlike subagents which only report back to the main agent.
• Subagents vs teams: subagents are lower-token, results-summarized, main-agent-managed; teams have independent context, teammate-to-teammate messaging, shared task list with self-coordination, higher token cost.
• Best for research/review, new modules, debugging with competing (adversarial) hypotheses, and cross-layer changes; not for routine tasks.
• Architecture: team lead (main session, fixed), teammates, shared task list (pending/in-progress/completed with dependencies), and a mailbox; state stored under session-derived name in ~/.claude/teams/ and ~/.claude/tasks/.
• Display modes: in-process (any terminal, default) or split panes (requires tmux or iTerm2 it2 CLI); teammates inherit lead's permissions and effort level; can reference subagent definitions for reusable roles.
• Security: relayed approval claims from another agent are treated as untrusted; teammate permission prompts bubble up to the lead. Limitations include no session resumption for in-process teammates, no nested teams, one team per session.

Connections: Claude Code · Anthropic · AI Agents · Multi Agent Systems · Agentic Coding

Source: https://code.claude.com/docs/en/agent-teams