Claude Agent Teams Complete Guide

Introduction to Agent Teams

Agent Teams is a revolutionary feature in Claude Code that allows multiple independent AI instances to collaborate like a real development team.

Imagine that in the past, using Claude Code was like being a project manager working with one exceptionally capable assistant. No matter how complex the task was, only that one assistant was doing the work. Now, with Agent Teams, you can assemble a full AI development team: one member can handle the frontend, one can handle the backend, one can handle testing, and they can work at the same time, communicate with each other, and collaborate to complete complex tasks.

From a single assistant to team collaboration

Before diving into Agent Teams, let's first understand the problem it solves.

Limitations of the single-AI mode:

When you use a single Claude instance to handle a complex project, you will run into these bottlenecks:

• Serial processing bottleneck: AI can only do one thing at a time. For example, when refactoring a project, it may need to analyze the authentication module first, then the database module, and finally the API module. These steps must be done sequentially, even if they do not depend on each other.

• Context crowding problem: All information lives in a single conversation window. As the conversation gets longer, important early details can get buried, and AI may forget key decisions discussed earlier.

• Single-perspective limitation: Only one AI is thinking, so there is no multi-angle discussion or validation. When complex design decisions appear, there is no "teammate" to debate with or provide a different perspective.

• Efficiency ceiling: Large refactors or multi-module development take a long time, and there is no way to speed them up through parallelism.

The Agent Teams solution:

Agent Teams solves these problems through parallel collaboration across multiple instances:

• True parallel work: Multiple AIs can work on different tasks simultaneously. One can handle the frontend UI, another the backend API, and another the database design, without interfering with each other.

• Independent context spaces: Every team member has its own full 200K token context window, so important information is not "forgotten" because the conversation gets too long.

• Team collaboration capability: Members can communicate directly, discuss design decisions, and validate code quality with each other, just like a real development team.

• A significant efficiency increase: According to Anthropic's internal testing, efficiency on large-scale project refactors can improve by around 50%.

Agent Teams vs Subagent

Before going deeper into the architecture of Agent Teams, we should first clear up a common point of confusion: what is the difference between Agent Teams and Subagent?

Both features involve "multiple AIs collaborating," but their collaboration models are completely different and suitable for different scenarios.

Core differences at a glance

An intuitive analogy

Subagent is like: a manager writing separate task slips for several assistants. Each assistant works independently based on its own task slip, and when finished, only returns the result to the manager. The assistants do not communicate directly, and the manager does not see the assistants' full thought process while they work.

You → Main Agent → Subagent A: "Analyze this file"
You → Main Agent → Subagent B: "Search for that function"
         ↓
    Subagent A completes → reports result to Main Agent
    Subagent B completes → reports result to Main Agent
         ↓
    Main Agent synthesizes the results → reports back to you

Agent Teams is like: a project manager leading a real development team. Team members can communicate, discuss, and collaborate directly, rather than routing every detail through the project manager.

You → Team Lead: "Build a user authentication feature"
         ↓
    Team Lead creates the team and assigns tasks
         ↓
    Teammate A: "@Teammate B, is the API interface design ready?"
    Teammate B: "Yes, here's the format..."
    Teammate C: "I reviewed the interface and found something we should discuss..."
         ↓
    Team members collaborate to finish the work → Team Lead synthesizes the result → reports back to you

When to use which one

Use Subagent when:

• You have a quick, clear, single task, such as "search for this error code"
• Tasks do not depend much on each other
• You want parallel execution, but do not need sustained discussion between members

Use Agent Teams when:

• You are doing a complex system refactor that spans multiple modules
• You need multi-angle analysis and discussion, such as a security expert and a performance expert debating a solution
• You need true parallel development, with frontend, backend, and testing happening at the same time
• Tasks require frequent coordination and information sharing

A simple summary

• Subagent: a task distribution tool that breaks a big task into smaller tasks and dispatches them to different "workers"
• Agent Teams: a real collaborative team where members can communicate, discuss, and work together like a real team

Core architecture

Agent Teams is not just a simple "open multiple instances" feature. It is a complete multi-agent collaboration system. To understand it, we need to understand its core components and how they work together.

Team composition

An Agent Team consists of four core components, each with its own responsibility, working together to complete complex tasks.

Team Lead

The Team Lead is the "brain" and "coordinator" of the entire team. It does not directly execute coding tasks. Instead, it is responsible for:

• Requirement analysis and task decomposition: breaking the user's complex requirements into multiple subtasks that can run in parallel
• Team creation and management: deciding how many members are needed and what each member should do
• Task assignment and scheduling: assigning tasks to the right members and managing task dependencies
• Result synthesis and quality control: collecting each member's work, integrating it, and doing the final review

Teammates

Teammates are the actual "developers" doing the work. Every Teammate is an independent Claude instance:

• Independent context window: each member has a full 200K token context window, completely isolated from the Team Lead and the other members
• Full tool permissions: they can use all tools such as Read, Write, Edit, and Bash
• Autonomous task pickup: they can independently select and claim tasks from the shared task board
• Direct communication ability: they can communicate directly with other members instead of always going through the Team Lead

TaskList

TaskList is the team's "project management tool," similar to Jira or Trello:

• Task status management: every task has a clear status: pending, in_progress, or completed
• Dependency management: tasks can define dependencies, and dependent tasks can only start after prerequisite tasks finish
• Automatic unlock mechanism: when one task is completed, the system automatically checks and unlocks tasks waiting on it
• File lock mechanism: when a member claims and starts a task, a lock file is created in the task directory to prevent multiple members from editing the same file at the same time

Messaging System

The messaging system is the "chat tool" between team members:

• Point-to-point communication: member A can send a message directly to member B
• Broadcast announcements: a message can be sent to all members at once
• File-system based: messages are stored as JSON files in ~/.claude/teams/{team-name}/inboxes/
• No network required: everything works entirely through the local file system, with no network connection or port listening needed

Collaboration flow

A typical Agent Teams workflow looks like this:

The user submits a complex requirement
       ↓
Team Lead analyzes the requirement and breaks it into tasks
       ↓
Creates team members and initializes TaskList
       ↓
       ├─→ Teammate A claims Task 1 ─┐
       ├─→ Teammate B claims Task 2 ─┼→ Run in parallel
       ├─→ Teammate C claims Task 3 ─┤
       │                             ↓
       └──────────────────────────── Members coordinate through the messaging system
                                     ↓
                          Once all tasks are complete, Team Lead synthesizes the result
                                     ↓
                          Final output is delivered to the user

File system layout

Agent Teams creates dedicated directories on your local file system to manage team state:

~/.claude/
├── teams/
│   └── {team-name}/
│       ├── config.json          # Team config (member list, model selection, etc.)
│       └── inboxes/
│           ├── team-lead.json   # Team Lead inbox
│           ├── teammate-1.json  # Member 1 inbox
│           └── teammate-2.json  # Member 2 inbox
└── tasks/
    └── {team-name}/
        ├── task-1.json          # Detailed info for Task 1
        ├── task-2.json          # Detailed info for Task 2
        └── current_tasks/
            └── parse_if_statement.txt  # Lock file created while a task is running

The advantage of this design is complete transparency: you can inspect team status, task progress, and the communication history between members at any time.

Quick start

Enable the experimental feature

Agent Teams is currently an experimental feature and is disabled by default. To use it, you need to enable it first.

The easiest way: let Claude Code enable it for you

Type this directly in Claude Code:

Help me enable Agent Teams in settings.json

Or:

Enable the experimental feature agentTeams

Claude Code will automatically modify ~/.claude/settings.json and add the following configuration:

{
  "experimental": {
    "agentTeams": true
  }
}

Restart Claude Code

After the configuration is added, fully quit and restart Claude Code, and the feature will take effect.

Manual configuration (if the automatic method does not work):

You can manually edit ~/.claude/settings.json and add or modify:

{
  "experimental": {
    "agentTeams": true
  }
}

How to verify it is enabled

After restarting Claude Code, try a conversation like this:

You: Can you help me create an Agent Team?

Claude: Yes! I can help you create an Agent Team to collaborate on a task...

If Claude understands and responds to the request to create a team, the feature has been enabled successfully.

Visual mode configuration (optional)

If you want to see team members' work in real time, you can configure split-pane display mode.

Let Claude Code configure it for you:

Type this directly in Claude Code:

Help me enable split-pane display mode for Agent Teams in settings.json, using tmux

Or:

Configure agent-teams to use split-panes mode

Install tmux (if you do not have it):

If tmux is not installed yet, you can ask Claude Code to install it:

Help me install tmux

Claude Code will automatically run the appropriate installation command based on your operating system, whether macOS or Linux.

What the configured result looks like:

After configuration, team members will work in different tmux panes, and you will be able to see all their output at the same time, like a "monitoring wall."

┌─────────────────┬─────────────────┬─────────────────┐
│  Teammate 1     │  Teammate 2     │  Teammate 3     │
│  Analyzing code │  Building API   │  Writing tests  │
│  ...            │  ...            │  ...            │
│                 │                 │                 │
└─────────────────┴─────────────────┴─────────────────┘

Manual configuration (if the automatic method does not work):

You can manually edit ~/.claude/settings.json:

{
  "experimental": {
    "agentTeams": true
  },
  "agent-teams": {
    "displayMode": "split-panes",
    "terminalMultiplexer": "tmux"
  }
}