Claude Code Agent Teams

Coordinate multiple Claude Code instances working together as a unified team with shared tasks, direct inter-agent messaging, and centralized management.

Fresh 🌱

What Are Agent Teams?

Agent teams let you orchestrate parallel work across multiple Claude Code sessions. One session acts as the team lead, coordinating work and synthesizing results, while independent teammates work on their own tasks with their own context windows.

Unlike subagents (which only report back), teammates can communicate directly with each other, making agent teams ideal for complex collaboration scenarios.

When to Use Agent Teams

Agent teams excel at parallel exploration:

• Research & Review: Multiple teammates investigate different aspects simultaneously
• New Features: Teammates own separate modules without stepping on each other
• Competing Hypotheses: Parallel debugging with different theories tested at once
• Cross-Layer Changes: Frontend, backend, and tests handled by different teammates

Key Features

• ✅ Independent Context Windows - Each teammate has separate Claude instance
• ✅ Direct Messaging - Teammates communicate with each other automatically
• ✅ Shared Task List - Centralized work coordination with dependencies
• ✅ Smart Delegation - Lead assigns work or teammates self-claim tasks
• ✅ Plan Approval - Require review before risky implementations
• ✅ Delegate Mode - Lead focuses on orchestration only, no code editing
• ✅ Quality Gates - Enforce standards with hooks on task completion

Quick Start

1. Enable Agent Teams

Add to settings.json:

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

2. Create Your First Team

Tell Claude what you want:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

3. Manage the Team

• Message teammates: Tell the security reviewer to [instruction]
• Monitor progress: View shared task list (Ctrl+T in-process mode)
• Redirect work: Wait for teammates to finish before proceeding
• Clean up: Clean up the team

Agent Teams vs Subagents

Aspect	Agent Teams	Subagents
Communication	Direct teammate messaging	Report back only
Independence	Fully autonomous	Return to caller
Coordination	Shared task list	Main agent manages
Best for	Collaboration & discussion	Focused tasks
Token cost	Higher	Lower

Documentation Sections

SOPs (Standard Operating Procedures)

Step-by-step guides for specific tasks:

• Enable and configure agent teams
• Create and manage teams
• Control display modes (terminal vs split panes)
• Handle tasks and delegation
• Clean up and troubleshoot

Workflows

Real-world patterns and strategies:

• Parallel code review across multiple reviewers
• Debugging with competing hypotheses
• Plan approval for complex work
• Delegate mode for orchestration-heavy tasks

Quick Reference

Fast lookup for:

• Terminal commands and syntax
• Keyboard shortcuts
• Architecture and components
• Troubleshooting common issues

Important Notes

• Experimental: Agent teams have known limitations around session resumption and shutdown
• Token Usage: Significantly higher than single session (scales with teammate count)
• One team per session: A lead manages one team at a time
• Best starting point: Begin with research/review tasks with clear boundaries

Get Started

Ready to orchestrate your first agent team?

1. Enable Agent Teams
2. Create Your First Team
3. Run a Parallel Code Review

Have questions? Use the chat widget in the bottom-right corner to ask about any topic!