Orchestrate teams of Claude Code sessions - Claude Code Docs
Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Agent teams are experimental and disabled by default. Enable them by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings.json or environment. Agent teams have known limitations around session resumption, task coordination, and shutdown behavior.
Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other. You can also talk to any teammate directly without going through the lead. Before you set up a team, check whether a lighter option does the job.
Subagents work within a single session, and with cross-session messaging Claude can pass findings between the sessions you run yourself. When to use agent teams Agent teams are most effective for tasks where parallel exploration adds real value. See use case examples for full scenarios. The strongest use cases are: Research and review : multiple teammates can investigate different aspects of a problem simultaneously, then share and challenge each other’s findings New modules or features : teammates can each own a separate piece without stepping on each other Debugging with competing hypotheses : teammates test different theories in parallel and converge on the answer faster Cross-layer coordination : changes that span frontend, backend, and tests, each owned by a different teammate Agent teams add coordination overhead and use significantly more tokens than a single session.
They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective. Compare with subagents Both agent teams and subagents let you parallelize work, but they operate differently. For separate sessions that pass messages to each other without a team, see cross-session messaging . Subagents report results back to the main agent.
In agent teams, teammates share a task list, claim work, and communicate directly with each other. Subagents Agent teams Context Own context window; results return to the caller Own context window; fully independent Communication Return a result to the caller. Subagents that Claude named when it spawned them can also message each other Teammates message each other directly Coordination Main agent manages all work Self-coordination through messages, plus a shared task list for agents that have the Task tools Best for Focused tasks where only the result matters Complex work requiring discussion and collaboration Token cost Lower: results summarized back to main context Higher: each teammate is a separate Claude instance Use subagents when you need quick, focused workers that report back.
Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own. Enable agent teams Agent teams are disabled by default. Enable them by setting the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1 , either in your shell environment or through settings.json : settings.json { "env" : { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" : "1" } } Enabling agent teams also changes ordinary delegation.
Claude may name a subagent on its own, and while agent teams are enabled, a subagent that Claude names launches as a teammate, so teams can form even when you didn’t ask for one. For more, see How Claude starts agent teams ; to turn the behavior off, see Claude spawns teammates instead of subagents . Spawning teammates also requires an interactive session. In non-interactive mode with the -p flag, including Agent SDK sessions, Claude doesn’t spawn teammates, and a subagent that Claude names runs as an ordinary subagent even with agent teams enabled.
Start your first agent team After enabling agent teams, describe the task and the teammates you want in natural language. Claude spawns them and coordinates work based on your prompt. This example works well because the three roles are independent and can explore the problem without waiting on each other: I'm designing a CLI tool that helps developers track TODO comments across their codebase. Spawn three teammates to explore this from different angles: one on UX, one on technical architecture, one playing devil's advocate.
From there, Claude populates a shared task list in a session that has the Task tools , spawns teammates for each perspective, has them explore the problem, and synthesizes findings when finished. Claude may sometimes use subagents instead of creating a team. Subagents appear in the same agent panel as teammates, so the panel alone doesn’t confirm a team formed. If Claude spawned subagents instead, ask again and explicitly request an agent team.
The lead’s terminal lists teammates in the agent panel below the prompt input. From the panel: Up and down arrows : select a teammate Enter : open the selected teammate’s transcript and message it directly Escape : clear the selection. While you’re viewing a teammate’s transcript, Escape interrupts that teammate’s current turn An idle teammate’s row stays in the panel while any teammate or subagent is still working, so you can select it to review its transcript or send it more work.
Once every agent in the panel is idle, idle rows hide after 30 seconds and reappear on the teammate’s next turn; the teammate stays running and addressable while hidden. When more than three teammates are idle at once, the rows beyond the first three collapse into a single row that counts the collapsed teammates, such as 2 idle agents when five are idle. Select it and press Enter to expand the collapsed rows, or press Esc to collapse them again.
Working teammates, failed teammates, and the teammate you’re viewing always keep their own rows. If you want each teammate in its own split pane, see Choose a display mode . Control your agent team Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions. Choose a display mode Agent teams support two display modes: In-process : all teammates run inside your main terminal.
Use the up and down arrow keys in the agent panel to select a teammate, then press Enter to view it and type to message it directly. Works in any terminal, no extra setup required. Split panes : each teammate gets its own pane. You can see everyone’s output at once and click into a pane to interact directly. Requires tmux, or iTerm2. tmux has known limitations on certain operating systems and traditionally works best on macOS.
Using tmux -CC in iTerm2 is the suggested entrypoint into tmux . With agent teams enabled , follow these steps to give each teammate its own pane: 1 Install tmux or set up iTerm2 Split-pane mode requires either tmux or iTerm2 with the it2 CLI . Set up the one you’ll run Claude Code in: tmux : install through your system’s package manager. See the tmux wiki for platform-specific instructions. iTerm2 : install the it2 CLI , then enable the Python API in iTerm2 > Settings > General > Magic > Enable Python API .
2 Turn on split panes Teammates run in-process until you change the teammateMode setting. Set it to "auto" in ~/.claude/settings.json : { "teammateMode" : "auto" } With "auto" , teammates open in split panes when you run Claude Code inside tmux or iTerm2, and run in-process in other terminals. 3 Start Claude Code and spawn teammates Run claude inside tmux or in iTerm2, then ask Claude to spawn teammates. If a setup prompt for it2 appears in iTerm2, select Install it2 now to open the panes in your iTerm2 window.
If you run Claude Code outside tmux and iTerm2, or the panes don’t open in your iTerm
The rest of this page is on the live site.