How to Use Agent Teams in Claude Code - Complete Guide 2026

You know that feeling when you're staring at a massive refactor, a multi-module feature, or a sprawling codebase review, and you think, "I wish I could clone myself"? Agent Teams in Claude Code is probably the closest you'll get.

Here's what you'll learn: How to enable Agent Teams, when the token cost is worth it, how to structure tasks so teammates don't overwrite each other's work, and which mistakes drain your budget. By the end, you'll turn 20-minute sequential tasks into 6-minute parallel sprints.

Imagine coordinating a small development team where each member tackles a different part of your project simultaneously -- except the team is made up of AI agents, each with their own context window, working in parallel while a lead agent orchestrates everything. That's Agent Teams. And it's surprisingly practical once you understand the mechanics.

What Are Claude Code Agent Teams?

Agent Teams is an experimental feature in Claude Code (research preview, February 2026) that lets you orchestrate multiple AI agents working in parallel. Powered by Claude Opus 4.6, the system consists of four core components:

• Team Lead: The main Claude Code session you interact with. It plans, spawns teammates, delegates tasks, and aggregates results.
• Teammates: Separate Claude instances, each with their own context window. They don't inherit the lead's conversation history but auto-load your CLAUDE.md, MCP servers, and skills.
• Task List: A shared work tracker with pending/in-progress/completed statuses and dependency management. Stored at ~/.claude/tasks/{team-name}/.
• Mailbox: Message-passing system for direct agent-to-agent communication.

Think of it like a scrum team where the lead is the product owner and each teammate owns a module. The difference? This team works at the speed of API calls.

Key Architecture Details

• Team config lives at ~/.claude/teams/{team-name}/config.json
• Each teammate starts with a blank conversation -- they only get your CLAUDE.md and the spawn prompt from the lead
• No file-level locking: if two teammates edit the same file, last write wins
• One team per session, no nested teams (teammates can't spawn their own teams)
• Sessions do not resume -- /resume and /rewind won't restore teammates

How to Enable Claude Code Agent Teams

Step 1: Add the Experimental Flag

Open your Claude Code settings file at ~/.claude/settings.json and add:

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

Save and restart Claude Code.

Alternative -- set it as an environment variable (won't persist across sessions):

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

The settings.json method is better because it loads automatically every time.

Step 2: Choose a Display Mode

Agent Teams supports three display modes. You can set these in settings.json or via command line:

Mode	How It Works	Terminal Support
in-process (default)	Teammates run in background. Use Shift+Up/Down to navigate.	Any terminal
tmux	Each teammate gets its own pane. See all output simultaneously.	tmux or iTerm2 only
auto	Uses tmux if available, falls back to in-process	Flexible

To set the display mode:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

Or on the command line:

claude --teammate-mode tmux

Tip: If you're on macOS, tmux -CC in iTerm2 gives the best experience. Split panes do not work in VS Code's terminal, Windows Terminal, or Ghostty.

Your First Agent Team (2-Minute Starter)

Let's run a complete example. Start Claude Code in any project directory:

claude

Then paste this prompt:

Create a team to review this project's README and package.json.
Spawn two teammates:
- "docs-reviewer": Read README.md, check for outdated info, missing sections
- "deps-reviewer": Read package.json, check for outdated or vulnerable dependencies

Have each write their findings and report back.

Within 30-60 seconds, the lead will:

1. Spawn both teammates
2. Each teammate reads their assigned files independently
3. Both report findings back to the lead
4. The lead aggregates and presents a summary

Press Ctrl+T at any time to see the task list and track progress.

That's it. You just coordinated two AI agents in parallel. Now let's learn when this actually saves time.

When to Use Claude Code Agent Teams

Agent Teams shine for parallelizable work with clear boundaries. Here's the decision framework:

Use Agent Teams For

Scenario	Why It Works
Multi-perspective code review	Security, performance, and test reviewers work simultaneously
Multi-module features	Frontend, backend, and DB teammates own separate files
Debugging with competing hypotheses	3 agents test 3 theories in parallel
Cross-layer coordination	Each teammate owns a layer (API, UI, tests)
Research with multiple angles	Each agent investigates a different library or approach

When NOT to Use Claude Code Agent Teams

Scenario	Why Teams Don't Help
Sequential tasks	Teammate B waits for A -- no parallelism benefit
Same-file edits	Last write wins, someone's work gets overwritten
Small or routine tasks	Coordination overhead exceeds task complexity
High coupling	Teammates constantly wait on each other

Task	Verdict	Reason
Refactor one 500-line file	Single session	One file, no parallelism
Review 20 files across 4 modules	Agent Teams	Naturally parallel
Fix a typo	Single session	Come on.
Build full-stack feature (DB + API + UI)	Agent Teams	Clear layer boundaries
Research 5 competing libraries	Agent Teams	Each agent evaluates one

How to Structure Tasks for Parallel Work

The golden rule: assign clear module ownership so teammates don't edit the same files.

Good Structure

Spawn a team for the notifications feature:
- backend-dev: Owns src/api/notifications.ts -- build endpoints
- frontend-dev: Owns src/components/NotificationCenter.tsx -- build UI
- test-dev: Owns tests/notifications/ -- write integration tests
- db-dev: Owns src/db/migrations/ -- create notifications table

Each teammate owns distinct files. Zero conflicts.

The Dependency Waves Pattern

When tasks have some dependencies, structure work in waves:

Wave 1 (all parallel): Define API contract, create DB schema, design UI mockups

Wave 2 (all parallel, after Wave 1): Implement endpoints, write migrations, build components

Wave 3 (all parallel, after Wave 2): Integration tests, E2E tests, documentation

You get parallelism within each wave while respecting the order between them. Aim for 5-6 tasks per teammate -- enough to stay productive without drowning.

How to Communicate with Claude Code Agent Teammates

Essential Keyboard Shortcuts

Shortcut	What It Does
Shift+Up/Down	Navigate between teammates (in-process mode)
Enter	View selected teammate's session
Escape	Interrupt a teammate's current work
Ctrl+T	Toggle the task list
Shift+Tab	Toggle delegate mode

Plan Approval: Save Tokens Before They're Spent

Here's a pro tip that will save you a fortune. Tell the lead to require plan approval before teammates start coding:

Spawn an architect teammate to refactor the auth module.
Require plan approval before they make any changes.

The workflow:

1. Teammate works in read-only plan mode
2. Sends a plan to the lead for review
3. Lead approves or rejects with feedback
4. If approved, teammate exits plan mode and implements
5. If rejected, teammate revises and resubmits

A plan costs about 10K tokens. Going in the wrong direction without one? 500K+ tokens. Easy math.

Delegate Mode

Press Shift+Tab and the lead becomes a pure coordinator -- no coding, just orchestrating. It can spawn teammates, send messages, manage tasks, and shut down agents, but it won't write code itself.

Use delegate mode when you have a large team (5+ teammates) and want the lead focused on coordination rather than getting distracted by implementation.

How to Monitor and Manage Your Team

Tracking Progress

Hit Ctrl+T to see the task list. You'll see which tasks are pending, in progress, or completed, and who owns each one.

When a Teammate Gets Stuck

Signs to watch for:

• No progress for 5+ minutes
• Same file being read repeatedly
• Error messages piling up

Your recovery options:

1. Send a message with a hint or redirect
2. Interrupt with Escape and give new instructions
3. Ask the lead to reassign the task to a new teammate
4. Shut down and respawn with fresh context

Shutting Down Properly

Don't just quit Claude Code with teammates running. You'll leave orphaned processes.

The right way:

1. Ask the lead: "Shut down all teammates"
2. Then: "Clean up the team"
3. Then exit Claude Code

If you accidentally quit, restart and tell the lead to clean up any orphaned teammates.

Real-World Examples

Example 1: Multi-Perspective Code Review

Review src/payments/ before merge. Create 4 reviewers:
- Security: PCI compliance, injection risks, data encryption
- Performance: N+1 queries, caching opportunities, bundle size
- Tests: Coverage gaps, missing edge cases, error handling
- UX: Error messages, loading states, accessibility

Result: 4 agents work simultaneously. Done in ~12 minutes instead of 45+. Each produces a focused report. The lead aggregates everything into prioritized action items.

One developer on HackerNews put it well: "4 agents, 6 tasks, ~6 min wall clock vs ~18-20 min sequential."

Example 2: Full-Stack Feature Build

Build export-to-PDF feature. Create a team:
- DB Engineer: export_jobs table, migrations, job queue
- Backend Dev: /api/export endpoint, PDF generation with Puppeteer
- Frontend Dev: Export button, progress modal, error states
- QA Engineer: Unit tests, API tests, E2E flow

Each teammate owns their layer. The lead coordinates the API contract, then teammates work independently.

Result: Feature complete in 35 minutes vs. 90+ sequential. Zero file conflicts.

Example 3: Adversarial Debugging

Your app crashes randomly for 3% of users. Nobody knows why.

Create a debugging team with 3 competing hypotheses:
- Agent A: Race condition in session management
- Agent B: Database connection pool exhaustion
- Agent C: Payment gateway timeout

Each agent: find evidence, propose a test, and implement a fix if confirmed.
Make teammates explicitly adversarial -- each should try to disprove the others.

The adversarial framing is key. When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. Multiple competing agents explore the full solution space.

Result: Agent B finds connection pool exhaustion in logs after 8 minutes. Total debug time: 15 minutes instead of potentially hours.

Managing Claude Code Agent Teams Costs

Let's be honest about token costs. Agent Teams multiplies your usage roughly proportional to team size.

Token Multiplier Table

Team Size	Token Multiplier	Typical Cost per Task
1 (single session)	1x	$0.05 - $0.15
2 agents	~2-3x	$0.10 - $0.40
3 agents	~3-4x	$0.15 - $0.60
5 agents	~5-7x	$0.25 - $1.00
10+ agents	~10-15x	$0.50 - $1.50+

Real-world benchmark: Anthropic's C Compiler project used 16 agents across nearly 2,000 sessions. Total cost: $20,000. Output: 100,000 lines of Rust code that compiles the Linux kernel on x86, ARM, and RISC-V.

Typical developer costs: $6/day average, below $12/day for 90% of users.

Cost Optimization Strategies

1. Use Sonnet for teammates, Opus for lead. The lead needs planning horsepower. Teammates executing well-defined tasks work great on the cheaper model -- ~60% cost reduction.

2. Require plan approval. 10K tokens for a plan vs. 500K+ for wrong implementation. This is the single biggest cost optimization.

3. Right-size your teams. 2-3 for reviews, 3-5 for features, 6+ only for large audits.

4. Shut down idle teammates. Active teammates consume tokens even when not working.

Is It Worth It?

Quick math: a 3-agent review costs ~$0.50 in tokens but saves 30 minutes. If your time is worth more than $1/hour (it is), Agent Teams pays for itself. For larger tasks, the ROI gets even better.

Common Mistakes with Claude Code Agent Teams

Mistake 1: Vague Spawn Prompts

Teammates start with empty context. "Review the code" tells them nothing.

Bad:

Create a team to fix the bugs.

Good:

Create a team to fix the 500 error on POST /api/orders.
Context: Error started after yesterday's migration. Logs show
"column 'tax_rate' does not exist". Migration added tax_rate
to orders table -- possibly a cache or rollback problem.

- Agent 1: Check if migration ran successfully, verify schema
- Agent 2: Investigate application-level DB schema caching
- Agent 3: Review rollback procedures, check for partial migrations

Think of it like onboarding a new developer. The more context, the better output. For tips on writing effective instructions, see our prompt engineering guide.

Mistake 2: Overlapping File Ownership

Two teammates editing utils.ts = one loses their work. There's no file-level locking.

Fix: Assign distinct files or directories to each teammate. If they must touch the same file, coordinate through the lead: "Agent A refactors first, then Agent B adds their changes."

Mistake 3: Lead Finishing Before Teammates

The lead sometimes wraps up while teammates are still working. Check Ctrl+T before accepting the lead's summary.

Fix: Explicitly tell the lead: "Wait for ALL teammates to complete before summarizing results."

Mistake 4: Trying to /resume

The /resume command doesn't restore teammates. After resuming, the lead may try messaging non-existent agents.

What you'll see:

Error: Teammate "security-reviewer" not found.

Fix: Tell the lead: "The teammates no longer exist. Spawn new ones."

Mistake 5: Spawning Too Many Agents

10+ teammates create coordination overhead that negates parallelism. The lead spends all its time coordinating instead of aggregating useful output.

Guidelines: 2-3 for reviews, 3-5 for features, 6-8 for large audits. Rarely more.

Subagents vs. Agent Teams: Which to Choose

Feature	Subagents	Agent Teams
Communication	Report to parent only	Direct peer-to-peer messaging
Coordination	Parent manages everything	Shared task list, self-claiming
Context	Own window, results summarized back	Own window, fully independent
Best for	Focused tasks where only the result matters	Complex work requiring discussion
Token cost	Lower (results compressed)	Higher (each = full session)

Rule of thumb: Use subagents for quick, focused research workers. Use Agent Teams when teammates need to share findings, challenge each other, and coordinate autonomously.

Summary and Next Steps

Agent Teams turns Claude Code from a solo assistant into a parallel development crew. When used for the right tasks -- code reviews, multi-module features, adversarial debugging -- it compresses hours into minutes.

Your action plan:

1. Enable Agent Teams by adding the flag to ~/.claude/settings.json
2. Run the 2-minute starter from this guide to see spawning in action
3. Start small with a code review using 2-3 teammates
4. Try a multi-module feature once you're comfortable with coordination
5. Track your costs and optimize with Sonnet teammates + plan approval

Keep Learning

• Claude Opus 4.6 Deep Dive -- Understand the model powering Agent Teams
• Cursor vs Copilot vs Claude Code -- Compare AI coding tools and multi-agent approaches
• Prompt Engineering 101 -- Write better spawn prompts for more productive teammates

Now go clone yourself. Your first team is just a prompt away.

Tutorial updated: February 2026. Tested on Claude Code with Opus 4.6.