How to Use Claude Code Agent Teams: Complete Setup Guide

February 2026 • 10 min read

On February 5, 2026, Anthropic shipped Claude Opus 4.6 alongside the biggest Claude Code feature drop yet: agent teams. Instead of a single agent working through your tasks sequentially, you can now orchestrate multiple Claude Code instances that coordinate autonomously, challenge each other's findings, and tackle complex codebases in parallel.

This guide walks you through everything you need to know: what agent teams are, how to enable and configure them, when they make sense over a single session, and how to use Beam to keep your multi-agent workflow organized.

What Are Agent Teams?

Agent teams are a new experimental feature in Claude Code that lets you coordinate multiple Claude Code instances working together on the same project. One session acts as the team lead, orchestrating the work, while separate teammates each operate in their own context window, working independently and communicating directly with each other.

This is fundamentally different from subagents. Subagents are lightweight helpers that report results back to a single parent session and cannot talk to each other. Agent team members, on the other hand, message directly, challenge each other's findings, and self-coordinate through a shared task list.

The architecture consists of four components:

• Team Lead -- Your main Claude Code session that creates the team, spawns teammates, and synthesizes results
• Teammates -- Separate Claude Code instances, each with its own full context window and Opus 4.6-level intelligence
• Shared Task List -- A coordinated list of work items with dependency tracking that teammates claim and complete
• Mailbox -- A messaging system that lets agents communicate with each other directly, not just through the lead

When to Use Agent Teams

Agent teams add coordination overhead and consume significantly more tokens (roughly 5x per teammate) than a single session. They are not the right tool for every task. Reserve them for work that genuinely benefits from multiple perspectives working in parallel:

• Research and review -- Multiple teammates investigate different aspects of a problem simultaneously, then share and challenge each other's findings
• New modules or features -- Teammates each own a separate piece of the implementation without stepping on each other's files
• Debugging with competing hypotheses -- Teammates test different theories in parallel and converge on the root cause faster, avoiding anchoring bias
• Cross-layer coordination -- Changes that span frontend, backend, and tests, each owned by a different teammate
• Large codebase audits -- Splitting review criteria (security, performance, test coverage) across dedicated reviewers

For sequential tasks, same-file edits, or work with many dependencies between steps, stick with a single session or subagents. Agent teams shine when teammates can operate independently.

Step-by-Step Setup

Agent teams are experimental and disabled by default. Here is how to enable and start using them.

1. Enable the Feature Flag

Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1. You can do this in your shell profile or in your Claude Code settings.json:

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

Or export it directly in your terminal before launching Claude Code:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

2. Choose a Display Mode

Agent teams support two display modes:

• In-process (default) -- All teammates run inside your main terminal. Use Shift+Up/Down to select a teammate and type to message them directly. Works in any terminal.
• Split panes -- Each teammate gets its own pane so you can see everyone's output at once. Requires tmux or iTerm2.

To set split-pane mode in your settings:

{
  "teammateMode": "tmux"
}

Or pass it as a flag when launching:

claude --teammate-mode tmux

3. Create Your First Agent Team

Once enabled, simply tell Claude Code to create an agent team and describe the task in natural language. Claude spawns the teammates and coordinates work based on your prompt:

Create an agent team to review the authentication module.
Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Claude creates the team, assigns roles, and the teammates begin working in parallel immediately.

4. Interact with Teammates

Each teammate is a full, independent Claude Code session. You can message any teammate directly:

• In-process mode: Press Shift+Up/Down to select a teammate. Press Enter to view their session. Press Escape to interrupt their current turn. Press Ctrl+T to toggle the shared task list.
• Split-pane mode: Click into a teammate's pane to interact with their session directly.

5. Use Delegate Mode

Sometimes the lead starts implementing tasks itself instead of delegating. Press Shift+Tab to cycle into delegate mode, which restricts the lead to coordination-only tools: spawning, messaging, shutting down teammates, and managing tasks. This keeps the lead focused on orchestration.

6. Clean Up When Done

When work is complete, ask the lead to shut down teammates and clean up:

Ask all teammates to shut down, then clean up the team.

The lead sends shutdown requests to each teammate (they can approve or reject with an explanation), then removes shared team resources. Always clean up through the lead, never through a teammate.

Organizing Agent Teams with Beam

Running three or more parallel Claude Code agents is powerful, but it creates an immediate organizational challenge: you need to track what each agent is doing, jump between them quickly, and keep their output separated. This is exactly the problem Beam was built to solve.

One Workspace Per Agent Team

Create a dedicated Beam workspace for your agent team. Press ⌘N to create a new workspace and name it after the task (e.g., "Auth Module Review"). Within this workspace:

• Tab 1: Team Lead session (your main Claude Code instance)
• Tab 2: Agent 1 output (security reviewer)
• Tab 3: Agent 2 output (performance reviewer)
• Tab 4: Agent 3 output (test coverage reviewer)

If you are using split-pane display mode with tmux, Beam's split panes (⌘⌥⌃T) let you see multiple agent outputs side by side within a single tab.

Quick Switcher for Agent Navigation

Press ⌘P to open Beam's Quick Switcher and fuzzy-search across all your workspaces, tabs, and layouts. When you have multiple agent teams running across different projects, this is the fastest way to jump to the exact agent you need.

Save Your Agent Team Layout

Once you have your agent team workspace configured perfectly, press ⌘S to save it as a layout. The next time you spin up an agent team for a similar task, restore the layout and your entire workspace structure is back instantly.

Real Workflow Example: Codebase Review with 3 Agents

Here is a concrete example of running a parallel code review using agent teams, organized with Beam.

Step 1: Set up your Beam workspace

1. Create a workspace named "PR Review #142"
2. Open 4 tabs: Lead, Security, Performance, Tests

Step 2: Launch the agent team

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.

Step 3: Monitor parallel progress

Each agent works independently in its own context window. The security reviewer examines token handling and input validation. The performance reviewer profiles database queries and memory usage. The test reviewer checks coverage gaps and edge cases. They can message each other directly -- for example, if the security reviewer finds an unvalidated input, it can alert the test reviewer to check whether that path has coverage.

Step 4: Review synthesized findings

When all agents finish, the lead synthesizes their findings into a unified report. You have three thorough, independent analyses instead of one reviewer that gravitates toward a single type of issue.

Tips for Getting the Most Out of Agent Teams

• Give teammates enough context -- Teammates load project context automatically (CLAUDE.md, MCP servers, skills), but they do not inherit the lead's conversation history. Include task-specific details in the spawn prompt so each agent has the context it needs.
• Size tasks appropriately -- Too small and coordination overhead exceeds the benefit. Too large and teammates work too long without check-ins. Aim for self-contained units that produce a clear deliverable: a function, a test file, a review. Having 5-6 tasks per teammate keeps everyone productive.
• Avoid file conflicts -- Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files.
• Start with read-heavy tasks -- If you are new to agent teams, begin with tasks that have clear boundaries and do not require writing code: reviewing a PR, researching a library, or investigating a bug. These show the value of parallel exploration without the coordination challenges of parallel implementation.
• Use hooks for quality gates -- The TeammateIdle hook runs when a teammate is about to go idle, and TaskCompleted runs when a task is being marked complete. Use these to enforce standards automatically.
• Monitor and steer -- 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 and tokens.
• Know when NOT to use teams -- Sequential tasks, same-file edits, work with many inter-step dependencies, or routine changes are all better handled by a single session or subagents. Agent teams are for parallelizable, complex work.

Summary

Claude Code agent teams, launched with Opus 4.6 on February 5, 2026, let you orchestrate multiple Claude Code instances that work in parallel, communicate directly with each other, and coordinate through a shared task list. They are the most powerful tool yet for codebase reviews, multi-module features, competing-hypothesis debugging, and cross-layer changes.

To get started:

1. Enable the feature with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
2. Tell Claude Code to create a team and describe your task in natural language
3. Use Beam to organize each agent into its own tab or pane for clean parallel tracking
4. Monitor, steer, and let the lead synthesize results when agents finish

Agent teams are experimental and have known limitations around session resumption, shutdown timing, and one-team-per-session constraints. But for the right tasks, they represent a genuine step change in what a single developer can accomplish with AI-assisted coding.