Claude Code Agent Teams: Powerful Guide

Agent teams let you coordinate multiple independent Claude Code sessions working together on a shared problem. One session acts as the team lead, spawning teammates that each run in their own context window and message each other directly. This experimental feature unlocks genuine parallel collaboration for research, review, and multi-layer implementation work that no single session can handle efficiently.

Agent Teams: What You’ll Learn

Agent teams represent a fundamentally different way to parallelize work in Claude Code. Instead of delegating side tasks within one session, you spin up multiple full sessions that share a task list and talk to each other. This guide walks through enabling the feature, launching teams, coordinating work, and monitoring everything with agent view. You will learn when agent teams beat subagents, how the shared task list coordinates work automatically, and how to avoid the coordination pitfalls that waste tokens.

What Are Agent Teams?

An agent team is a group of multiple Claude Code instances working together under a single coordination structure. The main session you start becomes the team lead. It spawns additional sessions called teammates, each running as a fully independent Claude Code conversation with its own context window.

The team shares three coordination primitives. A shared task list holds the work items that need doing, with each task moving through pending, in progress, and completed states. A mailbox system lets teammates send messages to each other directly by name. And the lead orchestrates everything, deciding what to spawn, assigning work, and synthesizing results when teammates finish.

The critical distinction is independence. Every teammate is a complete Claude Code session, not a lightweight worker. Each one loads project context including CLAUDE.md, MCP servers, and skills. Each maintains its own conversation history. And each can be addressed directly by you, without routing through the lead.

The Four Components of a Team

Every agent team consists of four architectural pieces working together. The team lead is your main Claude Code session, responsible for spawning teammates and coordinating work. Teammates are separate Claude Code instances that each own assigned tasks. The task list is the shared work queue all agents claim from. The mailbox handles messaging between agents.

Teams store their state locally on your machine. The team configuration lives at ~/.claude/teams/{team-name}/config.json, where the team name is session- followed by the first eight characters of your session ID. The task list lives at ~/.claude/tasks/{team-name}/. Claude Code generates both automatically at session startup and updates them as teammates join, go idle, or leave.

How Agent Teams Differ from Subagents and Workflows

Agent teams are one of four parallelization approaches in Claude Code, and choosing the wrong one wastes tokens and coordination effort. The differences come down to who coordinates, whether workers communicate, and how independent each session is.

Subagents run inside a single session as delegated workers. They do a side task in their own context and return a summary to the main agent. Subagents never talk to each other, only reporting back to the caller. Use them when only the result matters and workers do not need to share findings mid-task.

Workflows are single-session automation scripts that run many subagents in sequence and cross-check their results. A workflow holds the plan in a script rather than relying on turn-by-turn judgment. Use workflows for large jobs that outgrow a handful of subagents, like a codebase-wide audit or a 500-file migration.

Agent teams fill a different gap. When teammates need to discuss findings, challenge each other’s conclusions, and self-coordinate on a shared task list, agent teams provide the messaging and coordination layer that subagents and workflows lack. For the full comparison of Skills, Hooks, Subagents, and Plugins as extensibility mechanisms, see the extensibility guide.

Enabling Agent Teams

Agent teams are experimental and disabled by default. You enable them by setting the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1. Without this variable, no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates.

The cleanest approach is adding the variable to your settings.json file so it persists across sessions:

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

Once enabled, the feature activates automatically. You do not need to run a setup command or create a team explicitly. As of v2.1.178, spawning a teammate no longer needs a setup step, and cleanup happens automatically when the session exits. Earlier versions required asking Claude to create and name a team first using tools that no longer exist.

Starting Your First Agent Team

After enabling the feature, describe your task and the teammates you want in natural language. Claude decides how many teammates to spawn based on the task, or you can specify exactly what you need. Claude populates a shared task list, spawns teammates for each perspective, and synthesizes findings when they finish.

This example works well because the three roles are independent and can explore the problem without waiting on each other:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

You can also specify the exact number of teammates and their models explicitly. Teammates do not inherit the lead’s /model selection by default, so if you want a specific model, state it in your prompt:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

To change the default model teammates use when your prompt does not specify one, set the Default teammate model in /config. Pick Default to have teammates follow the lead’s current model, or choose a specific model to use for all teammates unless overridden.

Requiring Plan Approval

For complex or risky tasks, you can require teammates to plan before implementing. The teammate works in read-only plan mode until the lead approves its approach. When planning finishes, the teammate sends a plan approval request. The lead reviews and either approves or rejects with feedback. If rejected, the teammate revises and resubmits.

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

You influence the lead’s approval decisions by giving it criteria in your prompt. For example, tell it to only approve plans that include test coverage, or to reject plans that modify the database schema.

Choosing a Display Mode

Agent teams support two display modes that control how you see and interact with teammates. The default is in-process mode, where all teammates run inside your main terminal. You use the up and down arrow keys in the agent panel below the prompt input to select a teammate, then press Enter to view its transcript and message it directly.

Split-pane mode gives each teammate its own terminal pane. You see everyone’s output at once and click into a pane to interact directly. This mode requires tmux or iTerm2 with the it2 CLI installed. It does not work in VS Code’s integrated terminal, Windows Terminal, or Ghostty.

Control the mode with the teammateMode setting in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

The available values are in-process (default), auto (enables split panes when already inside tmux or iTerm2), tmux (enables split panes, auto-detecting tmux or iTerm2), and iterm2 (uses iTerm2 native split panes explicitly). For a single session, pass the mode as a flag:

claude --teammate-mode auto

The Shared Task List and Coordination

The shared task list is the coordination backbone of every agent team. The lead creates tasks and teammates work through them. Tasks have three states: pending, in progress, and completed. Tasks can also depend on other tasks, so a pending task with unresolved dependencies cannot be claimed until those dependencies finish.

Work assignment happens two ways. The lead can assign tasks explicitly by telling a specific teammate what to work on. Or teammates can 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 when multiple teammates try to claim the same task simultaneously.

The system manages dependencies automatically. When a teammate completes a task that other tasks depend on, the blocked tasks unblock without manual intervention. This lets you describe work as a dependency graph and let the team work through it in the right order.

Task States and Dependencies

Every task moves through a clear lifecycle. A task starts as pending when the lead creates it. It becomes in progress when a teammate claims it. It becomes completed when the teammate finishes the work. If a task has dependencies, it stays blocked and unclaimable until all its dependencies reach completed state.

The lead breaks work into tasks and assigns them automatically. If it is not creating enough tasks, ask it to split the work into smaller pieces. A good target is five to six tasks per teammate, which keeps everyone productive and lets the lead reassign work if someone gets stuck.

Communicating Between Teammates

Each teammate has its own context window and does not inherit the lead’s conversation history. When spawned, a teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills. It also receives the spawn prompt from the lead with task-specific instructions.

Teammates share information through several mechanisms. Messages between teammates are delivered automatically to recipients, so the lead does not need to poll for updates. When a teammate finishes and stops, it automatically notifies the lead. All agents can see task status and claim available work. And any teammate can message any other by name.

You can talk to teammates directly too. In in-process mode, use the arrow keys to select a teammate, press Enter to view its session, and type to send it a message. Press x on a selected teammate to stop it. Press Ctrl+T to toggle the task list. While viewing a teammate, plain text and skills go to that teammate, but built-in commands still run in the lead’s session.

Using Subagent Definitions for Teammates

When spawning a teammate, you can reference a subagent type from any scope: project, user, plugin, or CLI-defined. This lets you define a role once, such as a security-reviewer or test-runner, and reuse it both as a delegated subagent and as an agent team teammate.

To use a subagent definition, mention it by name when asking Claude to spawn the teammate:

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

The teammate honors that definition’s tools allowlist and model. The definition’s body is appended to the teammate’s system prompt as additional instructions rather than replacing it. Team coordination tools such as SendMessage and the task management tools are always available to a teammate, even when the tools field restricts other tools.

One limitation to note: the skills and mcpServers frontmatter fields in a subagent definition are not applied when that definition runs as a teammate. Teammates load skills and MCP servers from your project and user settings, the same as a regular session.

Hooks for Quality Gates

Use hooks to enforce rules when teammates finish work or when tasks change state. Three hook events give you control over team behavior at critical moments.

The TeammateIdle hook runs when a teammate is about to go idle. Exit with code 2 to send feedback and keep the teammate working rather than stopping. The TaskCreated hook runs when a task is being created. Exit with code 2 to prevent creation and send feedback to the lead. The TaskCompleted hook runs when a task is being marked complete. Exit with code 2 to prevent completion and send feedback if the work does not meet your bar.

These hooks let you build quality gates directly into the team workflow. For example, you could block task completion unless tests pass, or prevent a teammate from going idle until it has written a summary of its findings.

Permissions and Safety

Teammates start with the lead’s permission settings. If the lead runs with --dangerously-skip-permissions, all teammates do too. After spawning, you can change individual teammate modes, but you cannot set per-teammate modes at spawn time.

Safety boundaries are enforced strictly. When one agent sends another a message, the receiving agent is told it came from another Claude session, not from you. A teammate cannot approve a permission prompt or supply consent on your behalf. A teammate that was denied an action cannot relay it to another teammate to bypass the check. Teammate permission prompts bubble up to the lead session, so you approve them there yourself.

In auto mode, the classifier treats an approval claim relayed from another agent as untrusted input rather than confirmation from you. This prevents a chain of teammates from effectively granting each other permissions you never approved.

Agent View: Monitoring Parallel Sessions

Agent view, opened with claude agents, is a separate but related feature that gives you one screen for all your background sessions. It shows what is running, what needs your input, and what is done. Each background session is a full Claude Code conversation that keeps running without a terminal attached.

Use agent view when you have several independent tasks Claude can work on without you watching every step. Dispatch a bug fix, a pull request review, and a flaky-test investigation as three rows. Keep working in another window. Check back when a row shows it needs you or has a result. Agent view is in research preview and requires Claude Code v2.1.139 or later.

Reading Session State in Agent View

Each row in agent view starts with an icon showing the session’s state. Working shows an animated icon, meaning Claude is actively running tools or generating a response. Needs input shows yellow, meaning Claude is waiting on a question or permission decision. Idle shows dimmed. Completed shows green. Failed shows red. Stopped shows grey.

The icon’s shape also tells you whether the underlying process is running. An animated shape means the session process is alive and replies immediately. A dot means the process has exited but you can still peek, reply, or attach, and Claude restarts from where it left off. A special shape indicates a loop session sleeping between iterations.

When to Use Agent Teams

Agent teams are most effective for tasks where parallel exploration adds real value. The strongest use cases fall into four categories where independent investigation beats sequential work.

Research and review benefits from multiple teammates investigating different aspects of a problem simultaneously, then sharing and challenging each other’s findings. New modules or features let teammates each own a separate piece without stepping on each other. Debugging with competing hypotheses lets teammates test different theories in parallel and converge on the answer faster. Cross-layer coordination handles changes that span frontend, backend, and tests, each owned by a different teammate.

Agent teams add coordination overhead and use significantly more tokens than a single session. They work best when teammates can operate independently. For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective. Check the official agent teams documentation for the latest details.

A Worked Example

Imagine you are investigating a bug where users report the app exits after one message instead of staying connected. A single agent tends to find one plausible explanation and stop looking. Agent teams let you structure the investigation as an adversarial debate where teammates actively try to disprove each other’s theories.

You start by enabling the feature and describing the task to Claude with five teammates, each investigating a different hypothesis. The lead creates a shared task list with entries for network timeout, session token expiry, websocket handler crash, client-side reconnection logic, and server-side connection limits. Each teammate claims one hypothesis and begins investigating.

As teammates find evidence, they message each other directly. The network timeout investigator discovers elevated latency but also notices the reconnection logic does not trigger. It messages the reconnection logic teammate, who confirms a missing event listener. Meanwhile, the websocket handler investigator finds no crash logs, which it shares to eliminate that hypothesis.

The debate structure is the key mechanism. Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause. The lead synthesizes the consensus into a findings document, and you attach to any teammate to redirect its investigation if needed.

Throughout the process, you monitor from the agent panel. You see which teammates are working, which are idle, and which have found something worth reviewing. You step in only when a teammate needs direction or when the lead is ready to synthesize. The total token cost is higher than a single session, but the quality of the investigation is dramatically better because five independent lines of inquiry ran in parallel and cross-validated each other.

Agent Teams: Common Mistakes to Avoid

Agent teams are powerful but easy to misuse. These four mistakes account for most failed team workflows, and each has a straightforward fix once you recognize the pattern.

• Letting teammates edit the same files. Two teammates editing the same file leads to overwrites and lost work. Partition the work so each teammate owns a different set of files. Agent teams do not isolate teammates in worktrees automatically, so you must design the task boundaries to avoid file conflicts.
• Spawning too many teammates. Token costs scale linearly because each teammate has its own context window. Beyond a certain point, additional teammates do not speed up work proportionally. Start with three to five teammates for most workflows. Three focused teammates often outperform five scattered ones.
• Forgetting that teammates lack conversation history. Teammates load project context but do not inherit the lead’s conversation history. If your task depends on context discussed earlier in the session, include those details in the spawn prompt. Vague spawn prompts lead to teammates working from incomplete information.
• Not waiting for teammates to finish. Sometimes the lead starts implementing tasks itself instead of waiting for teammates. If you notice this, tell the lead to wait for teammates to complete their tasks before proceeding. Unattended teams run the risk of wasted effort when the lead duplicates work teammates are already doing.

Agent Teams: Best Practices

These practices come directly from the coordination challenges that teams face in production. Following them keeps your teams productive and your token spend reasonable.

• Give teammates enough context in the spawn prompt. Teammates load CLAUDE.md and project context automatically, but they do not see the lead’s conversation. Include task-specific details like file paths, architectural decisions, and constraints directly in the spawn instruction so each teammate starts with everything it needs.
• Choose an appropriate team size. Start with three to five teammates for most workflows. This balances parallel work with manageable coordination. Aim for five to six tasks per teammate to keep everyone productive without excessive context switching. Scale up only when the work genuinely benefits from simultaneous effort.
• Size tasks appropriately. Too small and coordination overhead exceeds the benefit. Too large and teammates work too long without check-ins, increasing the risk of wasted effort. The sweet spot is self-contained units that produce a clear deliverable, such as a function, a test file, or a review report.
• Start with research and review tasks. If you are new to agent teams, begin with tasks that have clear boundaries and do not require writing code. Reviewing a pull request, researching a library, or investigating a bug all show the value of parallel exploration without the coordination challenges of parallel implementation.
• Monitor and steer regularly. Check in on teammates’ progress, redirect approaches that are not working, and synthesize findings as they come in. Letting a team run unattended for too long increases the risk of wasted effort. Use the agent panel to watch state and attach to any teammate that needs direction.

Agent Teams: Frequently Asked Questions

How do I enable agent teams?

Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1 in your settings.json env block. Without it, no team forms and Claude never spawns or proposes teammates.

How are agent teams different from subagents?

Subagents run inside one session and only report results back. Agent teams are multiple independent sessions that share a task list and message each other directly, enabling genuine collaboration and debate.

Can teammates talk to each other directly?

Yes. Teammates use a mailbox system to send messages by name. The lead does not need to relay messages. Any teammate can reach any other teammate, and you can message teammates directly too.

Do teammates inherit the lead’s model?

Not by default. Teammates use their own model unless you specify one in the spawn prompt or set Default teammate model in /config to follow the lead’s current model selection.

Can I resume a session with an agent team?

No. In-process teammates do not survive session resumption. The lead may try to message teammates that no longer exist. Tell the lead to spawn new teammates after resuming a session with an agent team.

These limitations are expected to evolve as the experimental feature matures. Always check the official documentation for the most current behavior.

Agent teams multiply your Claude Code capacity by coordinating multiple independent sessions through a shared task list and direct messaging. Enable the feature, spawn teammates with clear context, partition work to avoid file conflicts, and monitor progress through the agent panel. Start with research tasks, keep teams small, and let teammates communicate to unlock genuine parallel collaboration.