When teams make sense — and when they don't
Agent teams add real coordination overhead. They pay off when work divides cleanly and parallelism wins; they hurt when the problem is tightly coupled or under-specified. If a single task runs and returns on its own, reach for a Claude Code sub-agent instead.
| Use a team when… | Avoid a team when… |
|---|---|
| Work splits into independent subtasks | Tasks are tightly coupled (high coordination cost) |
| A single context window would be exhausted | The problem isn't defined well enough to divide |
| Different parts benefit from different models | You need one coherent narrative or decision thread |
| You want parallel execution with coordination | A single focused session is simply faster |
Lead + teammate architecture
An agent team has one lead — your main session — and multiple teammates, which run as background sessions. The lead coordinates, assigns tasks, and merges results. Teammates work autonomously and report back.
Each teammate is independently configurable:
- Gets its own context window
- Can have its own model — Opus for complex reasoning, Sonnet for execution
- Can have a different tool set — e.g. restrict database teammates to read-only
- Can have a different permission mode — plan mode for risky operations
Starting your first team
You start a team in plain language, describing the split. Claude analyzes the task, proposes a division plan, and (if approval is required) waits for your sign-off before spawning teammates.
> Start an agent team to implement the new dashboard feature.
Split it into: (1) API endpoints, (2) React components, (3) database migrations, (4) tests.
Each teammate takes one area. I'll review and approve before you merge.Claude will then:
Analyze the task and create a division plan.
Show you the plan for approval (when require-plan-approval: true).
Spawn teammates with their specific assignments.
Coordinate the team via a shared scratchpad.
Report back once all teammates are done.
Configuration
Set team-wide defaults in settings:
{
"agentTeams": {
"maxTeammates": 4,
"requirePlanApproval": true,
"defaultPermissionMode": "acceptEdits",
"qualityGateHook": "npm test && npm run typecheck"
}
}Or specify teammates explicitly, mixing models and modes per role:
> Start a team with:
- Teammate 1 (Opus, plan mode): architect the data model
- Teammate 2 (Sonnet, acceptEdits): implement the API
- Teammate 3 (Sonnet, acceptEdits): write the testsQuality gates with hooks
An AgentTeamSubmit hook runs before a teammate can submit work. If the gate fails, the work is blocked — so "done" can never mean "compiled but broken."
{
"hooks": {
"AgentTeamSubmit": [
{
"command": "npm test && npm run typecheck && npm run lint",
"on_failure": "block_and_notify"
}
]
}
}Common failure patterns
Multi-agent systems fail in predictable ways. Here's how to head each one off:
File conflicts
Two teammates editing the same file. Use worktrees for strong isolation, or set explicit task boundaries in each assignment.
Lead shuts down early
The lead finishes before teammates do. Add "Wait for all teammates to finish" to the prompt.
Too many permission prompts
Teammates stuck in default mode. Set acceptEdits for well-understood tasks.
Orphaned tmux sessions
Use claude agents to find and clean up stray sessions.
Context divergence
Teammates drift out of sync on shared decisions. Use the shared scratchpad explicitly, or require teammates to post updates to a shared notes file.
Advanced pattern: competing hypotheses
Assign each teammate a different theory and let them investigate in parallel. This finds root causes faster than sequential debugging.
> Start a team to investigate the performance regression.
Teammate 1: hypothesis is N+1 queries in the product listing.
Teammate 2: hypothesis is unindexed joins in the user activity query.
Teammate 3: hypothesis is memory leak in the caching layer.
Each teammate investigates their hypothesis and provides evidence.
I'll evaluate and decide which to pursue.Practice project
Use an agent team to implement a full feature end-to-end: split the work into parallel API development, frontend development, test writing, and documentation. Time the run and compare it to your sequential estimate — and note exactly where coordination overhead showed up so you can scope teams better next time. For more, browse the full Claude Code tutorial series.
Agent Teams FAQ
What is a Claude Code agent team?
An agent team goes further than a single sub-agent: a coordinating lead spawns multiple autonomous teammates that work in parallel, each with its own context, model, tools, and permissions, then merges their results.
What is the difference between the lead and teammate agents?
An agent team has one lead — your main session — and multiple teammates that run as background sessions. The lead coordinates, assigns tasks, and merges results, while teammates work autonomously and report back.
How do agent teams work in parallel?
You describe the task split in plain language and Claude proposes a division plan. Once approved, it spawns teammates with specific assignments, coordinates them via a shared scratchpad, and reports back once all teammates are done.
How do quality gates and coordination work for agent teams?
An AgentTeamSubmit hook runs before a teammate can submit work, and if the gate fails the work is blocked — so "done" can never mean "compiled but broken." The lead coordinates the team through a shared scratchpad.
When should I use an agent team instead of a single sub-agent?
Use a team when work splits into independent subtasks, a single context window would be exhausted, different parts benefit from different models, or you want parallel execution with coordination. Avoid teams for tightly coupled or under-specified problems where a single focused session is faster.
Notes
Coordination overhead is real
Teams shine when subtasks are independent. If teammates need constant reconciliation on shared interfaces, a single focused session with plan mode is often faster and cheaper than three parallel contexts.
File conflicts are the default failure mode
Assign non-overlapping paths up front — e.g. src/api/ vs src/ui/. Two teammates editing the same module produces merge pain the lead must untangle manually.
Quality gates need fast feedback
AgentTeamSubmit hooks that run a full integration suite block teammates for minutes. Prefer typecheck + unit tests in the gate; reserve heavy suites for the lead's final merge pass.
Model choice per teammate matters
Use a faster model for boilerplate and docs teammates; reserve the strongest model for architecture and security review. Mismatched model tiers across teammates can produce inconsistent patterns.
Quick summary
- Use teams for divisible, parallelizable work — not tightly coupled or fuzzy problems
- A lead coordinates teammates, each with its own context, model, tools, and permissions
- Quality-gate hooks block broken submissions so "done" means tested and typechecked
- Guard against file conflicts, early shutdown, and context drift; competing hypotheses parallelize debugging