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.

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