Claude Code Agent Teams: Multi-Agent Coordination Guide (2026)

What Agent Teams Are

Agent Teams let you coordinate multiple Claude Code instances working on the same codebase in parallel. One session acts as the team lead, which creates the team, spawns teammates, assigns tasks, and synthesizes results. Each teammate is a full, independent Claude Code session with its own context window.

The key difference from working with a single session: teammates talk to each other. They claim tasks from a shared list, share discoveries mid-task, challenge each other's findings, and coordinate without the lead acting as intermediary. This makes them suited for problems where parallel exploration adds genuine value, not just parallel execution.

Agent Teams vs Subagents

Both subagents and agent teams parallelize work, but they solve different coordination problems. The distinction: do your workers need to talk to each other?

Use subagents when you need a quick worker to research something and report back. The caller fires the subagent, it does its job, and the result collapses into the main context. Subagents never talk to each other.

Use agent teams when the problem requires genuine collaboration. Code review needs cross-referencing security with performance. Feature implementation needs frontend, backend, and tests staying in sync. Bug investigation benefits from competing hypotheses where teammates actively try to disprove each other. These are coordination problems, and coordination requires communication between workers.

Enable Agent Teams

One setting. Add it to settings.json or your shell environment.

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

Or export it in your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Architecture

An agent team has four components:

Teams and tasks are stored locally at ~/.claude/teams/{team-name}/config.json and ~/.claude/tasks/{team-name}/. The team config contains a members array with each teammate's name, agent ID, and type. Teammates can read this file to discover other team members.

Display Modes

Two options for how teammates appear in your terminal:

# In settings.json
{
  "teammateMode": "in-process"
}

# Or as a CLI flag
claude --teammate-mode in-process

The default is "auto": split panes if you're already in tmux, in-process otherwise.

Step-by-Step Setup Tutorial

1. Enable the Feature

# Option A: settings.json
echo '{"env":{"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS":"1"}}' > ~/.claude/settings.json

# Option B: environment variable
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

2. Start Claude Code and Describe Your Team

Tell Claude the task and team structure in natural language. Be specific about roles.

# Example: parallel code review
> Create an agent team to review PR #142. Spawn three reviewers:
  - One focused on security implications
  - One checking performance impact
  - One validating test coverage
  Have them each review and report findings.

# Example: parallel feature development
> Create a team with 3 teammates to build the user settings page.
  - Teammate 1: backend API routes and database schema
  - Teammate 2: frontend React components
  - Teammate 3: integration tests
  Use Sonnet for each teammate.

Claude creates the team, spawns teammates, distributes the task list, and starts coordination. The lead's terminal lists all teammates and their current tasks.

3. Monitor and Steer

# Cycle through teammates (in-process mode)
Shift+Down    # next teammate
Shift+Down    # wraps back to lead after last teammate

# View a teammate's session
Enter         # expand teammate view
Escape        # interrupt their current turn

# Toggle task list
Ctrl+T

# Message a teammate directly
# (select them with Shift+Down, then type)

4. Clean Up

# Ask lead to shut down specific teammates
> Ask the researcher teammate to shut down

# Then clean up team resources
> Clean up the team

Communication Patterns

Teammates have two ways to communicate:

Direct Messages

Send a message to one specific teammate. Use this for targeted questions, feedback on a specific piece of work, or task handoffs.

Broadcasts

Send a message to all teammates simultaneously. Use sparingly. Token cost scales with team size because every teammate processes the broadcast in their context window. Good for team-wide announcements like "the database schema changed, update your queries."

Automatic Notifications

The system handles several notifications without manual intervention:

• Message delivery: When a teammate sends a message, it arrives at the recipient automatically. No polling.
• Idle notifications: When a teammate finishes and stops, the lead is notified immediately.
• Task unblocking: When a blocking task completes, dependent tasks automatically become available.

# Tell the lead to coordinate a handoff
> Tell the backend teammate to share the API schema
  with the frontend teammate before they start building components.

# Direct a teammate to challenge another
> Have the security reviewer challenge the performance
  reviewer's suggestion to cache auth tokens in memory.

# Broadcast a change
> Tell all teammates the database migration is complete
  and they should pull the latest schema.

Task Coordination

The shared task list is the coordination backbone. Tasks have three states: pending, in progress, and completed. Tasks can depend on other tasks, and a pending task with unresolved dependencies cannot be claimed.

Task Assignment

• Lead assigns: Tell the lead which task goes to which teammate.
• Self-claim: After finishing a task, a teammate picks up the next unassigned, unblocked task on its own.

Task claiming uses file locking to prevent race conditions. Two teammates cannot claim the same task simultaneously.

Plan Approval

For risky or complex tasks, require teammates to plan before implementing. The teammate works in read-only mode until the lead approves:

> Spawn an architect teammate to refactor the authentication module.
  Require plan approval before they make any changes.

# Teammate creates a plan -> sends it to lead -> lead reviews
# Lead approves: teammate exits plan mode, starts implementing
# Lead rejects with feedback: teammate revises and resubmits

# Influence approval criteria:
> Only approve plans that include test coverage.
> Reject plans that modify the database schema.

Quality Gates with Hooks

Use hooks to enforce rules automatically:

• TeammateIdle: Runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep them working.
• TaskCompleted: Runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback.

Worktree Isolation

The biggest risk with parallel agents editing the same codebase: file conflicts. Two teammates editing the same file leads to overwrites and wasted work. Git worktrees solve this.

The --worktree flag creates a full copy of your repository in a separate directory. Each teammate gets its own branch, its own files, and its own git index. They cannot overwrite each other's work. When done, you merge through standard git workflows.

> Create a team with worktree isolation:
  - Agent 1: feature/auth-backend (backend routes + DB schema)
  - Agent 2: feature/auth-frontend (React components)
  - Agent 3: feature/auth-tests (integration tests)

# Each agent commits to its own branch
# No file conflicts during work
# Merge branches when all agents complete

# Without worktrees (safe when editing different files):
> Create a team with 3 teammates to refactor these modules.
  Teammate 1 owns src/api/. Teammate 2 owns src/components/.
  Teammate 3 owns src/tests/. No overlapping files.

Best Use Cases

When NOT to Use Agent Teams

• Sequential tasks: If step 2 depends entirely on step 1, parallel agents add overhead with no benefit.
• Same-file edits: Two teammates editing one file is a recipe for merge conflicts.
• Simple tasks: A single session handles most work faster and cheaper than a team.
• Tight budget: Each teammate is a separate Claude instance. Costs scale linearly.

The C Compiler Story: 16 Agents, 100K Lines, $20K

Anthropic's engineering team ran the most ambitious multi-agent coding project published to date. The goal: build a Rust-based C compiler from scratch that compiles the Linux kernel.

What the Compiler Can Do

• Boots Linux 6.9 on x86, ARM, and RISC-V
• Compiles QEMU, FFmpeg, SQLite, PostgreSQL, Redis
• Passes 99% of GCC's torture test suite
• Runs Doom

How They Organized the Work

Each agent ran continuously, picking tasks from a shared queue. They used git-based synchronization with file locks in current_tasks/ to prevent duplicate work. Agents had specialized roles: code deduplication, performance optimization, efficient code generation, Rust code quality, and documentation.

What Worked

• High-quality test verification: "Claude will work autonomously to solve whatever problem I give it. So it's important that the task verifier is nearly perfect."
• GCC as oracle: When agents got stuck on kernel compilation, comparing against GCC's output let each agent fix different bugs independently.
• Careful context management: Minimal output, pre-computed statistics, deterministic sampling to identify regressions.

What Didn't

• 16-bit x86 code generation exceeded Linux's 32KB limit (deferred to GCC)
• The assembler and linker remained buggy (demo used GCC's toolchain)
• Code efficiency is lower than GCC even with all optimizations disabled
• Rust code quality is "nowhere near what an expert Rust programmer might produce"

Best Practices

Give Teammates Enough Context

Teammates load project context automatically (CLAUDE.md, MCP servers, skills) but do not inherit the lead's conversation history. Include task-specific details in the spawn prompt:

> Spawn a security reviewer with the prompt: "Review the authentication
  module at src/auth/ for security vulnerabilities. Focus on token handling,
  session management, and input validation. The app uses JWT tokens stored
  in httpOnly cookies. Report issues with severity ratings."

# Bad: "Review the auth code" (teammate has no context)
# Good: file paths, technology stack, what to look for, output format

Right-Size the Team

Start with 3-5 teammates. Aim for 5-6 tasks per teammate. Three focused teammates consistently outperform five scattered ones. Scale up only when the work genuinely splits into more independent tracks.

Size Tasks Appropriately

• Too small: Coordination overhead exceeds the benefit
• Too large: Teammates work too long without check-ins
• Right: Self-contained units with clear deliverables (a function, a test file, a review)

Avoid File Conflicts

Break work so each teammate owns a different set of files. If overlap is unavoidable, use worktree isolation.

Don't Let the Lead Do the Work

The lead sometimes starts implementing tasks instead of delegating. If you notice this:

> Wait for your teammates to complete their tasks before proceeding.

Pre-Approve Permissions

Teammate permission requests bubble up to the lead, causing friction. Pre-approve common operations in your permission settings before spawning teammates. Or run with --dangerously-skip-permissions if the work is low-risk and you want maximum autonomy.

Limitations and Gotchas

Frequently Asked Questions

What are Claude Code Agent Teams?

Agent Teams is an experimental feature (shipped February 2026 with Opus 4.6) that lets you coordinate multiple Claude Code instances working in parallel. One session is the team lead. It spawns teammates, each with their own context window, connected through a shared task list and direct messaging. Unlike subagents, teammates communicate directly with each other.

How do I enable Agent Teams?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your settings.json or shell environment. You need a Claude Pro or Max plan with Opus 4.6 access. Optionally install tmux or iTerm2 for split-pane mode.

What is the difference between Agent Teams and subagents?

Subagents are fire-and-forget workers within a single session. They do a job and report results back to the caller. They cannot talk to each other. Agent Teams are fully independent Claude Code instances that share a task list, claim work, and message each other directly. Teams cost more tokens but enable genuine collaboration on problems that require cross-referencing findings.

How many teammates should I use?

Start with 3-5. Token costs scale linearly. Coordination overhead increases with more members. Aim for 5-6 tasks per teammate. Three focused teammates often outperform five scattered ones. The C compiler project used 16, but that was an exceptional case with a very large, well-decomposed problem space.

Can teammates use git worktrees?

Yes. Each teammate can get its own worktree with a separate branch, files, and git index. This eliminates file conflicts during parallel work. Merge branches through standard git workflows when done. This is the safest approach when teammates might edit overlapping files.

How much do Agent Teams cost?

Each teammate has its own context window and consumes tokens independently. A 3-agent analysis costs roughly 3-5x a single session. For research, review, and new feature development, this is usually worthwhile. For routine tasks, stick with a single session or subagents.

Can I talk to teammates directly?

Yes. In in-process mode, press Shift+Down to cycle to any teammate and type to message them. In split-pane mode, click into a teammate's pane. Each teammate is a full Claude Code session that accepts instructions independently from the lead.

What happens if a teammate gets stuck?

Check their output (Shift+Down in in-process mode or click their pane). Give them additional instructions directly, or ask the lead to spawn a replacement. Teammates sometimes stop after errors instead of recovering.