Claude Code Agent Teams (Complete Guide) and how to

Claude Code’s Agent Teams feature marks a shift from sequential tasking to parallel, collaborative orchestration. While community tools like OpenClaw pioneered this "swarm" approach, Anthropic has now integrated it natively into the Claude Code research preview.

---

1. Prerequisites for Installation

Before enabling the feature, ensure you have the correct environment:

• Claude Code Version: You should be on version 2.1.32 or higher.

• Terminal Multiplexer (Optional but Recommended): For "split-pane mode," you’ll need tmux (Linux/macOS) or iTerm2 (macOS).

• CLAUDE.md: Every teammate loads this file automatically. Use it to define global project standards so you don't waste tokens re-explaining rules to every new teammate.

---

2. How to Enable Agent Teams

Agent teams are experimental and disabled by default. You can activate them in 30 seconds:

Option A: Persistent (Recommended)

Add the following to your ~/.claude/settings.json file:

JSON

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Option B: Session-Based

Export the variable directly in your terminal before running Claude:

• macOS/Linux: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

• Windows (PowerShell): $env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS="1"

---

3. Starting Your First Team

Once enabled, you don't need a specific command like /start-team. You simply prompt the lead agent to create one.

Example Prompt:

"I need to refactor the authentication module. Create an agent team: one teammate to rewrite the API routes, one to update the frontend hooks, and one to write integration tests for the new flow."

Selection of Display Modes

• In-Process (Default): All teammates run inside your current terminal. Use Shift + Up/Down to cycle through their views.

• Split-Pane: If you are inside a tmux session, Claude will automatically open new panes for each teammate. This is the best way to watch the "swarm" work in real-time.

---

4. Key Controls & "Delegate Mode"

Managing a team requires different shortcuts than a solo session:

Action	Shortcut / Command
Switch Teammate	Shift + Up / Shift + Down
Toggle Delegate Mode	Shift + Tab
Direct Message	Select the teammate's view and type normally.
Task Management	Ask the lead to "show the task list" or "reassign task X to teammate Y."

Pro Tip: Delegate Mode

When you toggle Delegate Mode, the Lead Agent stops trying to write code itself. It becomes a pure "Project Manager," focusing solely on coordinating teammates and managing the shared task list.

---

5. Best Practices & Token Management

Because each teammate is a fully independent Claude session, token usage can scale rapidly.

• Avoid File Collisions: Never assign two teammates to the same file. They will overwrite each other's work.

• Research First: Teams excel at "Competing Hypotheses." If you have a bug, tell the team: "Teammate A, investigate if this is a memory leak; Teammate B, check the database connection pool."

• Explicit Shutdown: When a teammate finishes, tell the lead: "Shut down the testing agent." Always run the /cleanup command through the Lead Agent once the project is finished to clear shared resources.

---

6. Current Limitations (Research Preview)

• No Session Resumption: If your main session crashes, in-process teammates cannot be "resumed" easily. You will likely need to spawn a new team.

• One Team per Session: You cannot run multiple independent teams from the same lead session.

• No Nested Teams: A teammate cannot currently spawn its own "sub-team."

Would you like me to help you draft a specific CLAUDE.md file to help your agents coordinate better on your current project?