Agent Teams in Claude Code: How to Coordinate AI Teams

You've already used Claude Code to create projects, edit code and automate tasks. But what if you could haveseveral agents working together, at the same time, each with a different specialty? That's what Agent Teams offers -- and it's one of the most ambitious features Anthropic has ever released.

Agent Teams is an experimental feature of Claude Code that allows you to coordinate multiple AI agents as if they were a real development team. One agent leads, others execute, and everyone communicates directly with each other. The result: projects that previously took hours with a single agent can now be done in minutes with a coordinated team.

In this guide, you will understand how Agent Teams works from the inside, how to configure it, what advanced hooks are available and -- most importantly -- when it makes sense to use a team instead of a solo agent.

1. What are Agent Teams (and why it changes everything)

Until now, Claude Code operated as a single agent. You talked to him, asked him for tasks, and he carried them out. Powerful, but limited to one "thread" of reasoning. Agent Teams breaks this limitation by introducing a familiar concept:teams.

An Agent Team is made up of:

• Team Lead:the main agent who receives its instruction, plans execution and distributes tasks
• Teammates:specialized agents that perform specific tasks in tollel
• Direct communication:teammates can chat with each other without having to go through team lead

Think about a real development team. You have a tech lead who understands the complete project, a frontend dev, a backend dev and someone from QA. Everyone does their part, but they talk to each other when they need to align something. Agent Teams replicates this dynamic with AI agents.

Why is this different from simply opening several Claude Code windows?

The fundamental difference andcoordination. When you open multiple Claude Code windows, each agent operates in isolation. They don't know what others are doing. With Agent Teams, the team lead maintains visibility of everything, distributes tasks intelligently and teammates share context. And the difference between having 5freelancerswho never speak to each other and have an integrated team.

Additionally, Agent Teams automatically manages conflicts. If two teammates try to edit the same file, the system coordinates the changes instead of creating conflicts. This is something you simply don't get with independent agents.

Feature status in 2026

Agent Teams is aexperimental feature. Anthropic released it as a preview to gather community feedback before stabilizing the API. In practice, this means it works well enough for real-world use, but the configuration syntax and hooks can change between versions. If you are willing to follow the updates, you can start using it now. If you prefer total stability, follow Anthropic's changelog and wait for the stable release.

2. Architecture: team lead, teammates and communication

Understanding the architecture is essential to using Agent Teams effectively. Let's break down each component.

Team Lead

The team lead is the agent that you interact directly with. When you enter an instruction in Claude Code with Agent Teams active, it is the team lead that receives it. He has specific responsibilities:

• Planning:Analyzes the task and decides how to divide it between teammates
• Delegation:assigns subtasks to specific teammates with clear instructions
• Supervision:monitors each teammate's progress
• Integration:combines teammates' results into a cohesive delivery
• Communication with the user:reports status, asks for clarification and delivers the final result

The team lead uses the most powerful model available (usually Opus) because it needs superior reasoning capabilities to coordinate. Teammates can use lighter models (Sonnet) for execution, which optimizes cost without sacrificing quality.

Teammates

Teammates are specialized agents. Each teammate has:

• A defined role:"frontend developer", "test engineer", "documentation writer", etc.
• Specific instructions:what should he do and how should he do it
• Access to tools:each teammate can have access to different tools
• Turn limit:each teammate operates with up to 50 tool-use turns per task

The limit of 50 tool-use turns is important. This means that each teammate can read files, write code, run tests, and make adjustments -- all within a single delegated task. It is sufficient for most subtasks, but very large tasks need to be broken down by the team lead.

Direct communication between teammates

This is the most powerful and least obvious feature. Teammates can communicate directly, without going through the team lead. In practice:

• The frontend teammate can ask the backend teammate "what format of JSON does the API return?"
• The testing teammate can warn the backend teammate "this endpoint is returning 500, did you change something?"
• The documentation teammate can ask the frontend teammate "give me the props for this component"

This lateral communication drastically reduces coordination time. Instead of everything having to go up to the team lead and back down, agents who need to align something do it directly. And exactly how it works in an efficient human team.

3. Sub-agents: agents within agents

Sub-agents existed before Agent Teams and remain a powerful tool. The difference is conceptual: a sub-agent and an agentlaunched by another agentto perform an isolated task.

How sub-agents work

When Claude Code (or a teammate within an Agent Team) encounters a task that requires isolated focus, he can launch a sub-agent. This sub-agent:

• Receives a specific instruction and a limited context
• Operates with50 tool-use turns
• Has access to the same tools as the parent agent (read/write files, execute commands)
• Returns the result to the agent who launched it
• Does not persist after completing the task

Sub-agents have asynchronous functions in the programming world. You delegate, the sub-agent executes, returns and disappears.

Sub-agent vs Teammate

Feature	Sub-agent	Teammate
Persistence	Temporary (a task)	Permanent during the session
Communication	Only with the parent agent	With team lead and other teammates
Shared context	Minimum (just what you received)	Broad (see the entire project)
Tool-use turns	Up to 50	Up to 50 per delegated task
Cost	Minor (limited context)	Greater (full context)
When to use	Punctual and isolated task	Interdependent and continuous tasks

Practical example of sub-agent

You ask Claude Code: "Refactor the authentication system and add tests." The main agent can launch a sub-agent specifically to write the tests while it does the refactoring itself. The sub-agent receives the context from the auth files, writes the tests, returns, and the main agent integrates everything.

4. Advanced Hooks for Agent Teams

Hooks are the mechanism that allows you to automate agent behaviors. Agent Teams introduces specific hooks for team coordination that do not exist in Claude Code solo.

TeammateIdle

Fired when a teammate finishes their task and becomes idle. Useful for:

• Redirect teammate to new task automatically
• Notify team lead that teammate is available
• Run validation scripts on work the teammate just completed

TaskCompleted

Fired when any task is delegated and completed. Unlike TeammateIdle, this hook focuses on the task and not the agent. You can use it to:

• Validate output quality automatically
• Trigger tests related to the completed task
• Update a project progress log
• Send notifications (webhook, Slack, etc.)

PreToolUse defer

The hookPreToolUsealready existed, but Agent Teams adds the optiondefer. When a teammate tries to use a tool and the hook returnsdefer, the action is paused and forwarded to the lead team for approval. This creates a system ofhierarchical permission:

• Teammates can read files and write code freely
• But destructive operations (deleting files, running deploy scripts) require approval from the lead team
• The team lead can approve or deny, and the teammate continues from that point

Agent hooks that read files and fetch code

Hooks can use the same tools as agents: read files, look for patterns in the code and make decisions based on the project context. A hook can, for example, read thepackage.jsonbefore allowing a teammate to install a dependency, checking if it already exists or if it conflicts with something.

5. Claude Code Review: review of PRs in tollel

Claude Code Review is a feature that uses the Agent Teams infrastructure to review pull requests. Instead of a single agent reading the entire PR,multiple agents review different parts simultaneously.

How it works

When you submit a PR for review by Claude Code, the system:

1. Analyze the full PR diff
2. Divides changed files into logical groups (frontend, backend, tests, config)
3. Assigns each group to a specialized review agent
4. Each reviewer analyzes his group in tollel
5. A coordinating agent consolidates reviews into a single feedback

The result is a faster and more in-depth review. While a single agent may miss details in a large PR, multiple specialized agents capture issues that would be overlooked in a cursory review.

In practice

What previously took 15-20 minutes of review by a single agent now completes in 3-5 minutes with tollel review. And the quality is superior because each reviewer focuses on their area of ​​expertise.

6. The /powerup command: interactive lessons

O /powerupis a Claude Code command that offers interactive lessons on advanced features. For Agent Teams, it is especially useful because the feature is new and best practices are still being established.

How to use

Each lesson lasts 5-10 minutes and includes practical exercises. You don't just read about the feature -- you use it in a guided environment. It's the fastest way to gain fluency in new features without having to read extensive documentation.

O /powerupAutomatically updates when new features are released. After each Claude Code update, it is worth running/powerupto see if there are new lessons.

7. Plugins with executables in bin/

Plugins are a way to extend Claude Code with costm tools. In the context of Agent Teams, plugins gain an extra dimension: you can create tools thatonly specific teammateshas access.

Structure of a plugin

A Claude Code plugin is simply an executable in the folder.claude/bin/of your project. It can be a bash script, a compiled binary, a scriptPython-- anything that runs in the terminal.

Each file in the folderbin/becomes a tool that Claude Code (and his teammates) can call upon. The file name and tool name.

Restricting access by teammate

With Agent Teams, you can configure which teammates have access to which plugins. The frontend teammate does not need (and should not) have access to thedb-migrate. The documentation teammate does not need access to thedeploy-staging.

This configuration creates setotion of responsibilities. Each teammate has access only to what they need, reducing the risk of unintentional operations and saving tokens (tools not made available do not consume context).

8. Multi-agent workflows in practice

Theory is important, but you want to know how it works in the real world. Here are concrete workflows that teams are using with Agent Teams.

Workflow 1: Complete feature (frontend + backend + tests)

You ask: "Implement the push notification system, with backend API, frontend component and complete tests."

1. Team leadAnalyzes the request and creates a plan with 3 subtasks
2. Teammate backendcreates the API endpoints, data model and shipping logic
3. Teammate frontendcreates the notification component, browser permissions and UI
4. Teammate QAwaits for backend and frontend to finish, then writes integration tests
5. Frontend and backend communicate directly to align the API contract
6. Team leadintegrates everything, runs the test suite and reports the result

Time with solo agent: 25-40 minutes. Time with Agent Team: 8-15 minutes. The savings come from tollelization -- while the backend creates the API, the frontend is already building the UI.

Workflow 2: Massive refactoring

You ask: "Migrate all class components to functional components with hooks."

1. Team leadidentifies all class components in the project (say 30 files)
2. Divide into groups of 10 and assign the3 teammates
3. Each teammate migrates its 10 components in tollel
4. Um QA teammateRun tests after each group of migrations
5. Team leadconsolidates and verifies that no regression was introduced

Workflow 3: Audit and correction

You ask: "Do a security, performance and accessibility audit, and fix what you find."

1. Security teammateanalyzes vulnerabilities (XSS, SQL injection, exposed secrets)
2. Performance Teammateanalyzes bundle size, lazy loading, cache headers
3. Accessibility Teammateanalyzes ARIA labels, contrast, keyboard navigation
4. Each generates a report and automatically applies fixes
5. Team leadconsolidates reports and prioritizes issues that no teammate could resolve alone

9. When to use an agent vs a team

Not everything needs an Agent Team. Knowing when to use each approach is just as important as knowing how to configure it.

Use a solo agent when:

• The task is sequential:each step depends on the previous one. An agent does better than a team standing still and waiting
• The scope is small:create a function, fix a bug, edit a file. One team and overkill
• You need constant interaction:creative decisions, brainstorming, iterative adjustments. A solo agent responds faster
• Cost matters:Solo agent uses fewer tokens. If you are optimizing cost, stay on the ground
• The project is new:When you're still exploring and don't know exactly what you want, a solo agent is more flexible

Use an Agent Team when:

• The task is tollelizable:frontend + backend + testing can be done at the same time
• The scope is large:refactoring of many files, complete feature with multiple layers
• Different specialties are required:the task requires knowledge of different areas that a single prompt does not cover well
• Time is more important than cost:You need fast delivery and accept paying more tokens
• Review is required:having one agent review another's work increases quality

Scenario	Recommendation	Reason
Fix a specific bug	Solo agent	Sequential and focused task
Create full CRUD	Agent Team (2-3)	Backend + frontend + tollel testing
Refatorar 50+ arquivos	Agent Team (3-4)	Massive tollelization
Write a README	Solo agent	Single and sequential task
Multi-area audit	Agent Team (3+)	Different specialties in tollel
Prototype an idea	Solo agent	Rapid iteration and exploration
Large PR code review	Claude Code Review	Parallel review by specialization

10. How to set up your first Agent Team

Let's go to practice. Configuring an Agent Team requires creating a configuration file in your project and defining the roles of each teammate.

Step 1: create the configuration file

In the root of your project, create the file.claude/teams.yaml:

Step 2: Activate Agent Teams

Step 3: use normally

With the team active, you interact normally with Claude Code. The difference is that the team lead will automatically delegate tasks when it makes sense. You don't need to micromanage -- the lead decides when to tollelize and when to do it themselves.

Notice how the frontend and backend communicated directly about the timestamp format without the lead needing to intervene. That's the magic of lateral communication.

Configuration tips

• Start with 2-3 teammates:do not create a team of 10 agents. Start simple, add as needed
• Be specific in the instructions:the clearer the role of each teammate, the better the coordination
• Use hooks from the beginning:configure at least PreToolUse with defer for destructive operations
• Monitor the cost: use /costto monitor consumption. Agent Teams consumes 2-4x more than solo agent
• Iterate:Adjust teammate instructions as you see what works and what doesn't