Claude Code Agent Teams: How to Run Parallel AI Agents on Your Codebase

A single Claude Code session can handle most coding tasks. But when you're debugging a sprawling issue, reviewing a large PR from multiple angles, or building a feature that spans frontend, backend, and tests — one agent isn't always enough. That's where Agent Teams come in.

Agent Teams let you coordinate multiple Claude Code instances working together on the same codebase. One session acts as the team lead, while independent teammates each run in their own context window, claim tasks, and communicate directly with each other. Think of it as spinning up a small engineering team on demand.

This feature shipped in Claude Code v2.1.32 as an experimental research preview, and it's already being used for serious work — including a project where 16 agents collaborated to build a 100,000-line C compiler from scratch.

Here's everything you need to know to start using Agent Teams effectively.

How Agent Teams Differ from Subagents

Before diving in, it's worth understanding where Agent Teams fit relative to Claude Code's existing subagents. Both let you parallelize work, but they operate differently.

Subagents run inside your current session. They execute a focused task, return a result, and that's it. They can't talk to each other or coordinate without the main agent acting as intermediary.

Agent Teams are fully independent Claude Code instances. Each teammate has its own 1M-token context window, can message other teammates directly, and coordinates through a shared task list. The team lead orchestrates, but teammates self-organize.

The rule of thumb: use subagents when you need quick workers that report back. Use Agent Teams when teammates need to share findings, challenge each other, and coordinate independently.

Setting Up Agent Teams

Agent Teams are disabled by default. You need Claude Code v2.1.32+ and access to the Opus 4.6 model (available on Pro or Max plans).

Step 1: Enable the Feature

Add the experimental flag to your settings.json:

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

Or set it as an environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Step 2: (Optional) Install tmux for Split Panes

Agent Teams support two display modes:

• In-process (default): all teammates run in your main terminal. Use Shift+Down to cycle between them.
• Split panes: each teammate gets its own terminal pane. Requires tmux or iTerm2.

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

To set split-pane mode permanently, add to ~/.claude.json:

{
  "teammateMode": "tmux"
}

Or pass it per session:

claude --teammate-mode in-process

Step 3: Start a Team

There's no configuration file to write. You describe the team conversationally and Claude builds it:

Create an agent team with 3 teammates to refactor the payment module.
One handles the API layer, one handles the database queries, one writes tests.

Claude creates the team lead, spawns teammates, distributes tasks, and starts coordinating.

Core Concepts

The Shared Task List

Every agent team revolves around a shared task list. The lead creates tasks, teammates claim and complete them. Tasks have three states: pending, in progress, and completed. Tasks can also have dependencies — a pending task with unresolved dependencies stays blocked until those dependencies are completed.

Task claiming uses file locking to prevent race conditions when multiple teammates try to grab the same task simultaneously.

Press Ctrl+T in-process mode to toggle the task list view.

Peer-to-Peer Messaging

Unlike subagents, teammates communicate directly through a mailbox system. A teammate can message one specific peer, or broadcast to the entire team. Messages are delivered automatically — the lead doesn't need to relay them.

This is what makes Agent Teams powerful for debugging. One teammate can say "I found the issue is in the auth middleware" and another can immediately pivot their investigation.

Teammate Lifecycle

Teammates can be spawned, given work, redirected, and shut down:

Ask the researcher teammate to shut down

The teammate can approve or reject the shutdown request with an explanation. When you're done with the entire team:

Clean up the team

Note: Always use the lead to clean up. Teammates should not run cleanup themselves, as their team context may not resolve correctly.

Real-World Use Cases

1. Parallel Code Review

A single reviewer tends to fixate on one type of issue at a time. With Agent Teams, you can split review criteria into independent domains:

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.

Each reviewer applies a different lens to the same PR. The lead synthesizes all findings into a unified review.

2. Debugging with Competing Hypotheses

When the root cause is unclear, a single agent tends to find one plausible explanation and stop. Agent Teams fix this by making teammates adversarial:

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them
talk to each other to try to disprove each other's theories, like a
scientific debate.

The debate structure fights anchoring bias. The theory that survives multiple agents actively trying to disprove it is far more likely to be the actual root cause.

3. Cross-Layer Feature Development

For features that span multiple layers — API, database, frontend, tests — each teammate can own a distinct slice:

Create an agent team with 4 teammates to build the user notification system.
- One handles the database schema and migrations
- One builds the API endpoints
- One implements the frontend components
- One writes integration tests
Use Sonnet for each teammate.

4. Large-Scale Codebase Research

Need to understand how authentication works across 50 files before making changes? Spawn research teammates that each investigate a different aspect and share findings with each other in real time.

Best Practices

Give Teammates Enough Context

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

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

Keep Teams Small

Start with 3-5 teammates. Token costs scale linearly with each teammate, and coordination overhead increases with team size. Three focused teammates often outperform five scattered ones.

A good heuristic: aim for 5-6 tasks per teammate. If you have 15 independent tasks, 3 teammates is a solid starting point.

Size Tasks Appropriately

• Too small: coordination overhead exceeds the benefit
• Too large: teammates work too long without check-ins, increasing wasted effort
• Right-sized: self-contained units that produce a clear deliverable — a function, a test file, a review

Avoid File Conflicts

Two teammates editing the same file leads to overwrites. Structure work so each teammate owns a different set of files. For tasks that need file-level isolation, consider using worktree isolation instead — each agent gets its own git worktree with a full copy of the codebase.

Require Plan Approval for Risky Work

For complex or risky tasks, require teammates to plan before implementing:

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

The teammate works in read-only plan mode until the lead approves. You can influence approval criteria: "only approve plans that include test coverage" or "reject plans that modify the database schema."

Use Subagent Definitions for Reusable Roles

Define roles once in .claude/agents/ and reuse them as teammates:

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Glob, Grep
model: sonnet
---
You are a security-focused code reviewer...

Then reference it when spawning:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Use Hooks for Quality Gates

Agent Teams support hooks for enforcing rules:

• TeammateIdle: runs when a teammate finishes. Exit with code 2 to send feedback and keep the teammate working.
• TaskCreated: runs when a task is created. Exit with code 2 to reject with feedback.
• TaskCompleted: runs when a task is marked complete. Exit with code 2 to reject completion.

Current Limitations

Agent Teams are still experimental. Key limitations to be aware of:

• No session resumption: /resume and /rewind don't restore in-process teammates. After resuming, spawn new teammates if needed.
• One team per session: clean up the current team before starting a new one.
• No nested teams: teammates cannot spawn their own teams.
• All teammates share the lead's permission mode: you can change individual modes after spawning, but not at spawn time.
• Split panes require tmux or iTerm2: not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.
• Task status can lag: teammates sometimes fail to mark tasks complete. Nudge them if work appears stuck.

Agent Teams vs. Manual Worktrees

You can also run parallel Claude Code sessions manually using claude --worktree:

claude --worktree feature-auth
claude --worktree bugfix-123

Each session gets its own git worktree — a separate working directory with its own branch. This is simpler than Agent Teams but lacks the shared task list, messaging, and automated coordination.

Use manual worktrees when you want to run independent sessions yourself. Use Agent Teams when you want Claude to handle coordination automatically.

Getting Started

If you're new to Agent Teams, start with tasks that have clear boundaries and don't require writing code:

1. Review a PR from three different perspectives (security, performance, testing)
2. Research a library with teammates investigating different aspects
3. Investigate a bug with competing hypotheses

These workflows show the value of parallel exploration without the coordination challenges of parallel implementation. Once you're comfortable, scale up to feature development and refactoring tasks.

The key insight is that Agent Teams aren't about doing the same work faster — they're about doing different work simultaneously. The best results come when each teammate has a distinct role and clear ownership over their part of the problem.