# Claude Code Agent Teams Experimental feature (enable with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). Agent teams coordinate multiple Claude Code instances working together. One session acts as team lead, spawning teammates that work independently in their own context windows. Unlike subagents (which run within a single session and only report back), teammates can communicate directly with each other via a shared mailbox and task list. ## When to use - Research/review: multiple teammates investigate different aspects in parallel - New modules/features: each teammate owns a separate piece - Debugging with competing hypotheses: test different theories simultaneously - Cross-layer coordination: frontend, backend, and tests each owned by different teammates Not worth it for sequential tasks, same-file edits, or heavily dependent work — use a single session or subagents instead. ## Display modes - **In-process** (default): all teammates in the main terminal. `Shift+Down` to cycle between them - **Split panes**: each teammate gets its own pane (requires tmux or iTerm2). Set `teammateMode` in settings or pass `--teammate-mode` ## Key mechanics - Teammates load project context (CLAUDE.md, MCP, skills) but NOT the lead's conversation history - Task list is shared; teammates can self-claim unblocked tasks - File locking prevents race conditions on task claiming - Teams stored in `~/.claude/teams/{team-name}/config.json`, tasks in `~/.claude/tasks/{team-name}/` - Hooks: `TeammateIdle` and `TaskCompleted` for quality gates - No session resumption for in-process teammates, no nested teams, one team per session ## References - Agent teams: https://code.claude.com/docs/en/agent-teams ## Related - [[Claude Code]] - [[Claude Code Tasks]] - [[AI Agents]] - [[tmux-ide]]