# How to install and use Claude Code Agent Teams (Reverse-engineered)

Source: https://www.youtube.com/watch?v=S2WTTMXYcYY
Recap page: https://rapidrecap.app/video/S2WTTMXYcYY
Generated: 2026-02-07T11:33:45.128+00:00

---
## Quick Overview

The video reverse-engineers and demonstrates how to install and use the Claude Code Agent Teams feature by enabling the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1, creating configuration files in the .claude/teams folder, and initiating a multi-agent investigation session via the command line, which allows agents to communicate and debate hypotheses to achieve a consensus, superior to single-agent investigations.

**Key Points:**
- Agent Teams are enabled globally by setting the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to "1" in the shell or settings.json.
- Teams are configured by creating a folder structure under .claude/teams, including a config.json for team metadata and numbered JSON files (1.json, 2.json, etc.) in a tasks subdirectory for individual assignments.
- The main agent initiates a session using the command 'claude --teammate-mode tmux' to spawn a collaborative environment where sub-agents work on assigned tasks concurrently.
- Sub-agents communicate via a 'Send Message' tool, which allows one-to-one or broadcast messages, and team leads can use 'Shutdown Request' messages to terminate team members' sessions.
- The multi-agent debate structure, where agents challenge each other's theories, produces a clearer, more precise conclusion than sequential single-agent investigations, as shown in the debugging example where five agents resolved a complex bug.
- The new tools introduced for teams include TeamCreate, TaskCreate x N, Task x N, TaskUpdate, and TeamDelete, all defined by JSON schemas.
- LangFuse integration is shown to be useful for tracing and visualizing the complex inter-agent communication history, including message types like 'message', 'broadcast', and 'shutdown_request'.

![Screenshot at 00:19: The whiteboard diagram illustrates the shift from a single 'Sub-agent' handling a 'Task' to the 'Agent team' structure initiated by 'TeamCreate', followed by 'TaskCreate x N', leading to parallel 'TaskUpdate' execution by multiple sub-agents.](https://ss.rapidrecap.app/screens/S2WTTMXYcYY/00-00-19.jpg)

**Context:** The video provides a detailed, reverse-engineered tutorial on setting up and running the experimental Agent Teams feature within Claude Code. This feature allows multiple specialized AI agents to collaborate, debate findings, and work in parallel on complex tasks, contrasting sharply with the previous single-agent task execution model. The demonstration involves setting up a specific team structure to investigate a software bug related to disappearing design draft nodes.

## Detailed Analysis

The video details the process of setting up and utilizing Claude Code's experimental Agent Teams feature, which significantly enhances problem-solving by enabling collaborative, adversarial investigations among multiple specialized agents. To activate this feature, users must set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to "1" either in their shell environment or globally in ~/.claude/settings.json. Once enabled, teams are structured by creating a dedicated directory under ~/.claude/teams/<team_name> containing a config.json file for team metadata (name, description, lead agent) and a tasks/ subdirectory populated with numbered JSON files (1.json, 2.json, etc.) defining individual agent tasks. The investigation begins by launching Claude Code in a special mode using 'claude --teammate-mode tmux', which spawns a multi-pane terminal environment where the main agent orchestrates the team. The process involves TeamCreate, TaskCreate x N (to define the list of tasks), and Task x N (to distribute tasks). Agents communicate using a 'Send Message' tool that supports direct messages, broadcasts, and administrative commands like 'shutdown_request' used by team leads to terminate subordinate sessions. The power of this approach is demonstrated through debugging a complex issue where five agents debated hypotheses, leading to a consensus document that clearly identified the root causes—a superior outcome to single-agent debugging. The necessary tools for team management include TeamCreate, TaskCreate, TaskUpdate, and TeamDelete, all governed by specific JSON schemas. Finally, the video shows how integrating with LangFuse allows for deep tracing of all internal communications, including tool invocations and messages, providing full visibility into the team's reasoning process.

### Enabling Agent Teams

- Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to "1" in shell or settings.json
- Agent Teams are disabled by default
- Requires Claude Code v2.1.34 or later

### Team Structure Configuration

- Create directory structure under ~/.claude/teams/<team_name>
- config.json defines team ID, description, and leadAgentId
- Tasks are defined in tasks/*.json files, including subject, description, owner, status, and dependency fields (blocks, blockedBy)

### Launching a Team Session

- Use 'claude --teammate-mode tmux' command in the terminal
- This spawns a multi-pane environment for team interaction

### Team Workflow

- Main agent uses TeamCreate -> TaskCreate x N -> Task x N (distribution)
- Sub-agents execute tasks, use TaskUpdate to report status, and Send Message for communication
- Team leads can issue shutdown_request via Send Message

### Key Tools for Teams

- TeamCreate (defines team)
- TaskCreate (defines list of tasks)
- TaskUpdate (updates task status)
- SendMessage (enables agent-to-agent communication, including broadcast and shutdown requests)

### Advantages over Sub-agents

- Agent Teams allow agents to explicitly challenge each other's theories (scientific debate) to avoid premature stopping on the first plausible explanation
- Enables parallel investigation from different directions

### Tracing and Visibility

- LangFuse integration provides detailed traces of all model calls, tool usage, and agent-to-agent messages, offering transparency into the complex team dynamics

![Screenshot at 00:00: Viewing the Claude Docs page detailing the 'Run agent teams' feature within the 'Build with Claude Code' section.](https://ss.rapidrecap.app/screens/S2WTTMXYcYY/00-00-00.jpg)
![Screenshot at 00:24: Whiteboard diagram comparing the simple 'Sub-agent' model \(single task execution\) to the complex 'Agent team' model \(collaborative, multi-step process\).](https://ss.rapidrecap.app/screens/S2WTTMXYcYY/00-00-24.jpg)
![Screenshot at 01:00: Demonstration of enabling Agent Teams by setting the CLAUDE\_CODE\_EXPERIMENTAL\_AGENT\_TEAMS environment variable to "1" in the settings.json file.](https://ss.rapidrecap.app/screens/S2WTTMXYcYY/00-01-00.jpg)
![Screenshot at 01:11: The main agent initiating a team session using the command 'claude --teammate-mode tmux' after enabling the feature.](https://ss.rapidrecap.app/screens/S2WTTMXYcYY/00-01-11.jpg)
![Screenshot at 07:10: LangFuse tracing interface showing the sequence of tool invocations, including multiple 'Tool: SendMessage' calls between agents during the investigation.](https://ss.rapidrecap.app/screens/S2WTTMXYcYY/00-07-10.jpg)