Agent teams
Several sessions working together under a team lead. See what it is, how it works, how it is used and what to watch for, with pictures and examples.
What it is
teams let several sessions work on one job together. One session is the team lead: it splits the work, hands out tasks and combines the results. Each teammate is a full Claude Code session with its own , and teammates send messages straight to each other through a mailbox. The whole team shares one task list, and each task is pending, in progress or completed. The feature is still experimental, so you must turn it on yourself.
How it works
-
Turn on the experimental setting
-
Describe the task and the teammates
-
Teammates claim tasks and talk directly
-
The lead combines the results
How to use it
-
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSset it to
1in your or in theenvblock ofsettings.jsonto turn teams on, and to0to turn them off again. -
teammateModechoose how teammates appear. The default
in-processkeeps everyone in one ; with or iTerm2 each teammate can get its own split pane. -
Agent panel — in the lead's terminal, pick a teammate with the arrow keys and press Enter to read its work and message it directly.
-
review — for example, ask for three teammates to review one , one each for , performance and test coverage.
Watch out
Every teammate is a separate instance, so a team uses far more than one session; start with 3–5 teammates. Two teammates editing the same file overwrite each other, so give each one its own files, and do not confuse teammates with , which only report back to the session that made them. /resume does not bring back in-process teammates, and a claude -p run never spawns teammates.
Related terms
Original and official docs
This page explains the term in plain words. The original is the authority: if they differ, follow the original.
- See this term in the originalClaude Code Docs — Glossary Anthropic · checked 2026-10-19
- Anthropic — Claude Code docs: Orchestrate teams of Claude Code sessions — Enable agent teams(opens in a new window)
- Anthropic — Claude Code docs: Orchestrate teams of Claude Code sessions — Compare with subagents(opens in a new window)
- Anthropic — Agent teams(opens in a new window)