Claude Code Agent Teams Guide

Claude Code agent teams let multiple Claude Code sessions work together. One session acts as the team lead. Teammates work independently, maintain their own context windows, share a task list, and can message each other directly.

This guide explains when agent teams make sense, how they differ from subagents, how to enable the experimental feature, how to structure a first team, how teammate models and plan approval work, and how to keep parallel work from turning into a messy diff.

Quick Answer

Use Claude Code agent teams when the work benefits from independent parallel exploration. Good uses include:

1. Parallel code review.
2. Competing debugging hypotheses.
3. Cross-layer feature planning.
4. Independent module work.
5. Architecture evaluation from multiple perspectives.
6. Research that needs challenge and synthesis.

Do not use agent teams for small sequential edits, same-file changes, simple bug fixes, or tasks where every step depends on the previous step. Agent teams add coordination overhead and use more tokens than one session or one subagent.

Agent Teams Are Experimental

Agent teams are experimental and disabled by default. Enable them by setting:

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

You can also set the environment variable in your shell:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Claude Code agent teams require Claude Code v2.1.32 or later. Check your version:

claude --version

Because this is an experimental feature, expect rough edges around resuming sessions, shutdown behavior, task coordination, and terminal display. Use it first on low-risk work.

Agent Teams vs Subagents

Subagents and agent teams both enable parallel work, but the workflow is different.

Question	Subagents	Agent Teams
Where do workers live?	Inside one session	Separate Claude Code sessions
Communication	Report back to caller	Teammates message each other
Coordination	Main agent manages work	Shared task list and team lead
Best for	Focused side tasks	Collaborative multi-part work
Token cost	Lower	Higher
Human interaction	Mostly with main session	You can talk to teammates directly

Use subagents when you only need the result. Use agent teams when workers need to compare findings, challenge each other, or coordinate across different parts of a larger task.

For focused delegation, read the Claude Code Subagents Guide.

Start Your First Agent Team

After enabling agent teams, ask Claude to create a team with explicit roles:

Create an agent team to review this authentication refactor.
Use three teammates:
1. security reviewer
2. test coverage reviewer
3. backward compatibility reviewer

Each teammate should inspect independently, then the lead should synthesize the top risks.
Do not edit files.

This is a good first task because each teammate can work independently. Nobody needs to modify files, and the final output is a small review summary.

For implementation work, be more careful:

Create an agent team to plan the dashboard redesign.
One teammate owns frontend structure, one owns API impact, and one owns test strategy.
Require plan approval before any teammate edits files.

Plan approval matters when the work could create overlapping edits.

Control Teammates

The team lead coordinates work. You can tell the lead what you want in normal language:

Ask the test teammate to focus only on changed behavior.
Ask the security teammate to ignore style and check auth boundaries.

Agent teams support display modes:

1. In-process: teammates run inside the main terminal. You can cycle through them.
2. Split panes: teammates appear in separate panes through supported terminal tooling.

To force in-process mode:

claude --teammate-mode in-process

In-process mode is the easiest first setup because it needs less terminal configuration.

Specify Teammates And Models

Claude can decide how many teammates to create, but explicit roles are usually better:

Create a team with 4 teammates:
- frontend reviewer
- backend reviewer
- test strategist
- release risk reviewer
Use Sonnet for each teammate.

Teammates do not always inherit the lead model automatically. If model choice matters, say it in the prompt or configure the default teammate model in Claude Code settings.

Use cheaper or faster models for broad research. Use stronger models for security review, architecture tradeoffs, and tricky debugging.

Require Plan Approval

For risky work, require teammates to plan before editing:

Spawn a backend teammate to refactor the billing route.
Require plan approval before they make any changes.
Only approve plans that preserve existing API behavior and include tests.

The teammate works in read-only plan mode first. The lead reviews the plan and approves or rejects it. To shape the lead's judgment, include approval criteria:

1. Must include test coverage.
2. Must avoid database schema changes.
3. Must not touch production secrets.
4. Must preserve public API names.
5. Must keep edits in assigned files.

Plan approval is not a substitute for human review, but it reduces blind parallel edits.

Shared Task List

Agent teams coordinate with a shared task list. Tasks can be pending, in progress, or completed. Tasks can also depend on other tasks.

This makes agent teams better than a loose group chat for parallel work. The lead can assign tasks to specific teammates, or teammates can claim unblocked tasks after finishing their current work.

Good task design:

1. One task has one owner.
2. File ownership is explicit.
3. Dependencies are named.
4. Verification is part of the task.
5. Completion requires evidence.

Bad task design:

1. "Improve the backend."
2. "Clean up everything."
3. "Make it production ready."
4. "Everyone look at the same files."
5. "Fix whatever you find."

Parallel agents magnify ambiguity. Clear task boundaries matter more, not less.

Use Subagent Definitions As Teammate Roles

Agent teams can reference existing subagent definitions. That lets you define a role once and reuse it as a teammate.

Example:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

The teammate can use the subagent definition's instructions, tool limits, and model. This is useful for teams that already maintain project or user subagents.

There is one important distinction: teammate coordination tools remain available, and not every subagent frontmatter field applies the same way in a team context. Treat the subagent definition as reusable role guidance, not a full replacement for team instructions.

Quality Gates With Hooks

Hooks can enforce team rules when teammates create tasks, complete tasks, or go idle.

Useful team hooks include:

1. Block task completion unless verification is described.
2. Reject vague task titles.
3. Keep a teammate working when the report lacks file paths.
4. Require a risk summary before completion.
5. Prevent tasks that touch forbidden paths.

For hook basics, see the Claude Code Hooks Guide.

Quality hooks are especially useful with agent teams because more workers means more chances for someone to mark a task done too early.

Cleanup And Shutdown

When work is done, ask the lead to shut down teammates and clean up:

Ask each teammate to summarize final status, then shut down.
Clean up the team after all teammates stop.

The lead should handle cleanup. Teammates should not run cleanup themselves because they may not have the right team context.

Cleanup matters because team state is stored locally while active. The team lead manages resources such as task lists and team configuration. Do not hand-edit those generated files.

Best First Workflows

Start with read-only workflows:

1. Parallel code review.
2. Security review plus test review.
3. Competing root-cause analysis.
4. Architecture tradeoff review.
5. Migration plan critique.

Move to implementation only after you are comfortable with task assignment, model choice, plan approval, and cleanup.

When implementation begins, split by ownership:

Create an agent team for this feature.
Frontend teammate owns only app/dashboard files.
Backend teammate owns only api/dashboard files.
Test teammate owns only tests/dashboard files.
Require plan approval before edits.

If two teammates need the same files, make one teammate the owner and have the other review.

Common Mistakes

The first mistake is using agent teams for ordinary single-threaded work. If one agent can do it cleanly, use one agent.

The second mistake is spawning too many teammates. Start with two or three.

The third mistake is vague ownership. Parallel work needs explicit file and responsibility boundaries.

The fourth mistake is skipping cleanup. Ask the lead to shut down and clean up when finished.

The fifth mistake is treating teammate output as proof. Evidence still means files, diffs, tests, logs, and review.

Final Recommendation

Use Claude Code agent teams for work where independent perspectives are valuable: review, research, debugging hypotheses, and cross-layer planning. Start read-only, keep team size small, require plan approval for risky edits, and make the lead synthesize evidence before you act.

Agent teams are not a default coding mode. They are a high-leverage option for tasks where multiple independent contexts can produce a better decision than one crowded conversation.

Related Claude Code Tutorials

• Claude Code Quick Start
• Claude Code Subagents Guide
• Claude Code Plugins Guide
• Claude Code Skills and Slash Commands Guide
• Claude Code Hooks Guide
• Claude Code MCP Guide
• Claude Code GitHub Actions Guide
• Codex vs Claude Code

Official Sources

• Run agent teams
• Run agents in parallel
• Create custom subagents
• Hooks reference