Claude Code Agent Teams: How to Enable and Use Multi-Agent Collaboration

Anthropic just dropped Claude Opus 4.6, and the headline feature is Agent Teams — the ability to coordinate multiple Claude Code instances working together on a single task. Instead of one agent working through problems sequentially, you can now spin up a team where each member owns a piece of the puzzle and they communicate directly with each other.

Here’s how to enable it and start using it.

What Are Agent Teams?

Agent Teams let you coordinate multiple Claude Code sessions working in parallel. One session acts as the team lead, orchestrating work and synthesizing results. The rest are teammates — independent Claude Code instances, each with their own context window, that can message each other directly.

This is different from subagents, which run within a single session and only report back to the main agent. With Agent Teams, teammates can challenge each other’s findings, debate approaches, and self-coordinate through a shared task list.

The architecture looks like this:

Component	Role
Team Lead	Your main session — creates the team, spawns teammates, coordinates work
Teammates	Separate Claude Code instances working on assigned tasks
Task List	Shared work items that teammates claim and complete, with dependency tracking
Mailbox	Messaging system for direct inter-agent communication

Enabling Agent Teams

Agent Teams are experimental and disabled by default. You need to flip one switch to turn them on.

Option 1: Settings File (Recommended)

Add the environment variable to your ~/.claude/settings.json:

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

If you already have a settings file with other configuration, just merge the env block in. For example, here’s what a more complete settings file might look like:

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)"
    ]
  },
  "model": "opus",
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Option 2: Shell Environment

If you just want to try it for a single session:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Using Agent Teams

Once enabled, you describe your task and team structure in natural language. Claude handles the rest — creating the team, spawning teammates, and coordinating the work.

Starting a Team

Create an agent team to refactor the auth module. Spawn three teammates:
- One for the JWT token handling
- One for session management
- One for writing integration tests

Claude creates the team, assigns tasks, and lets the teammates work in parallel. You can watch progress in real time.

Display Modes

There are two ways to visualize your team:

• In-process (default): All teammates run in your main terminal. Use Shift+Up/Down to select and message teammates directly.
• Split panes: Each teammate gets its own terminal pane. Requires tmux or iTerm2.

To force split-pane mode:

claude --teammate-mode tmux

Or set it permanently in settings:

{
  "teammateMode": "tmux"
}

Delegate Mode

By default, the lead sometimes starts implementing tasks itself instead of waiting for teammates. If you want the lead to focus purely on coordination, press Shift+Tab to toggle delegate mode. This restricts the lead to spawning, messaging, and task management — no code touching.

Plan Approval

For risky work, you can require teammates to submit plans before implementing:

Spawn an architect teammate to redesign the database layer.
Require plan approval before they make any changes.

The teammate works in read-only plan mode, submits their approach, and only starts implementing after the lead approves.

Talking to Teammates Directly

Each teammate is a full Claude Code session. You can message any of them directly:

• In-process mode: Shift+Up/Down to select, then type your message
• Split panes: Click into the teammate’s pane

This is useful for redirecting a teammate’s approach or asking follow-up questions without going through the lead.

When to Use Agent Teams (and When Not To)

Agent Teams shine for parallel exploration — work where multiple independent perspectives add real value:

• Code review from multiple angles — security, performance, and test coverage simultaneously
• Debugging with competing hypotheses — teammates test different theories and debate
• New feature modules — each teammate owns a separate piece
• Cross-layer changes — frontend, backend, and tests each owned by a different agent

They’re not great for:

• Sequential tasks with heavy dependencies
• Same-file edits (teammates will overwrite each other)
• Simple, routine work (the coordination overhead isn’t worth it)
• Tasks where a single session or subagent would suffice

Agent Teams vs Subagents

	Subagents	Agent Teams
Communication	Report back to main agent only	Teammates message each other directly
Coordination	Main agent manages all work	Shared task list with self-coordination
Best for	Focused tasks where only the result matters	Complex work requiring discussion
Token cost	Lower	Higher — each teammate is a separate instance

Limitations to Know About

This is still experimental. A few rough edges:

• No session resumption — /resume won’t restore in-process teammates
• One team per session — clean up the current team before starting a new one
• No nested teams — teammates can’t spawn their own teams
• Higher token costs — each teammate is a separate Claude instance, billed independently
• Split panes not supported in VS Code terminal, Windows Terminal, or Ghostty

Key Takeaways

• Enable with one setting: add CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" to the env block in ~/.claude/settings.json
• Natural language control: describe your team and tasks, Claude handles the orchestration
• Best for parallel work: code review, debugging, new features with independent modules
• Delegate mode (Shift+Tab) keeps the lead focused on coordination
• Higher token costs — use judiciously for complex tasks where parallel exploration genuinely adds value
• Still experimental — expect some rough edges around session resumption and shutdown behavior

Resources

• Agent Teams Documentation
• Subagents Documentation
• Claude Code Settings
• Anthropic releases Opus 4.6 with new ‘agent teams’ — TechCrunch

---

Published: February 2026