Claude Code Agent Teams: A Builder's Guide to Parallel AI Coding

Claude Code Agent Teams, Anthropic's parallel AI coding feature, changed how we build software. We've been running Claude Code in production daily since it launched — single-session workflows, sub-agents for focused tasks, AGENTS.md contracts driving everything. When Anthropic shipped Agent Teams with Opus 4.6 on February 5, 2026, we dropped everything and tested it on our actual codebase. Here's what we learned — the practical stuff nobody's covering yet.

What Claude Code Agent Teams Actually Are

Claude Code Agent Teams let you orchestrate multiple Claude Code sessions working together on a shared project. One session acts as the team lead. It spawns teammates, assigns tasks via a shared task list, and synthesizes results. Each teammate gets its own context window and can message other teammates directly.

This is fundamentally different from sub-agents. Sub-agents run inside your main session's context, do focused work, and report results back. They can't talk to each other. Agent Teams creates independent sessions that collaborate through a mailbox system and shared task list — think project team versus freelancer queue.

Setting Up Claude Code Agent Teams

Enable the feature with a single environment variable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Or persist it in your Claude Code settings:

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

That's it. No additional dependencies, no external tools. The feature is built into Claude Code 2.1 natively.

Plan Mode vs Delegate Mode

This is where most guides fall short. There are two distinct ways to run Claude Code Agent Teams, and choosing wrong wastes tokens and produces worse results.

Plan Mode (Default)

The lead agent plans the work AND participates in execution. It can read files, write code, and run commands — while also coordinating teammates. This sounds efficient but creates a problem: the lead gets distracted by implementation details instead of focusing on coordination.

When to use Plan Mode:

• Small teams (2-3 teammates) where the lead's direct contributions matter
• Tasks where the lead needs to validate teammate output in real-time
• Quick prototyping where overhead of strict delegation isn't worth it

Delegate Mode (Shift+Tab)

Press Shift+Tab after starting a team to lock the lead into coordination-only mode. The lead can spawn teammates, send messages, manage the task list, and shut down workers — but it cannot touch code directly. Teammates handle all implementation.

When to use Delegate Mode:

• Larger teams (4+ teammates) where the lead should focus purely on orchestration
• Complex cross-layer refactors where coordination quality matters more than lead contributions
• Production workflows where you want clean separation between planning and execution

Known issue (as of February 2026): Delegate mode has a bug where teammates inherit the lead's restricted tool access. If your teammates suddenly can't read files or write code, this is why. The workaround is to explicitly grant full permissions in each teammate's spawning prompt. Track this at github.com/anthropics/claude-code/issues/25037.

The Claude Code Agent Teams Contract-First Approach

The single biggest factor in Claude Code Agent Teams success isn't the feature itself — it's your AGENTS.md file. We've been running contract-first development for months, and Agent Teams amplifies its importance by an order of magnitude.

Why Contracts Matter More With Agent Teams

When a single Claude Code session reads your AGENTS.md, it gets one interpretation of your project's rules. When four Agent Teams teammates each read it independently, you get four interpretations. Without explicit contracts, teammates make conflicting assumptions about code style, architecture patterns, testing requirements, and file organization.

Our AGENTS.md Structure for Teams

# AGENTS.md

## Architecture Rules
- All API routes use the handler pattern in /src/handlers/
- Database queries go through /src/db/queries/ — never inline SQL
- Every public function has JSDoc with @param and @returns

## File Ownership (Critical for Teams)
- /src/api/ → API teammate owns this
- /src/db/ → Database teammate owns this
- /src/components/ → Frontend teammate owns this
- /src/tests/ → Test teammate owns this

## Code Standards
- TypeScript strict mode, no `any` types
- Error handling: always use Result<T, E> pattern
- Imports: absolute paths via @/ alias

## Team Coordination Rules
- Before modifying a shared file, message the file owner
- Integration points documented in /docs/interfaces.md
- All teammates run `npm test` before reporting task complete

The File Ownership section is the key addition for teams. Without it, two teammates editing the same file creates merge conflicts that waste tokens and produce inconsistent code.

When to Use Claude Code Agent Teams vs Sub-Agents

After two weeks of daily use, here's our decision framework:

The key question: Do your workers need to talk to each other? If yes, Claude Code Agent Teams. If they just need to do work and report back, sub-agents are faster and cheaper.

Real-World Claude Code Agent Teams Patterns

Pattern 1: The Feature Squad

Lead → Spawns 3 teammates:
  ├── API Teammate: Builds REST endpoints
  ├── DB Teammate: Creates migrations + queries
  └── Test Teammate: Writes integration tests as API + DB work completes

The test teammate watches messages from the other two and writes tests against the interfaces they define. This produces better test coverage than writing tests after implementation because the test teammate challenges assumptions in real-time.

Pattern 2: The Research Debate

Lead → Spawns 2-3 teammates:
  ├── Advocate A: Argues for approach X with evidence
  ├── Advocate B: Argues for approach Y with evidence
  └── (Optional) Critic: Tries to break both approaches

Each teammate researches independently, then they message each other with findings. The lead synthesizes the strongest arguments from all sides. We use this for architectural decisions where there's no obvious right answer.

Pattern 3: The Parallel Processor

Lead → Spawns N teammates:
  ├── Worker 1: Processes files 1-50
  ├── Worker 2: Processes files 51-100
  └── Worker N: Processes files (N-1)*50+1 to N*50

For large-scale operations like codebase-wide refactors or bulk file processing. Each worker owns a distinct file range. No communication needed between workers — the lead just distributes and collects.

Practical Claude Code Agent Teams Tips From Daily Use

1. Start Small

Don't spawn 6 teammates on day one. Start with 2 teammates on a well-defined task. Learn the coordination patterns before scaling up.

2. Be Explicit About Scope

Vague prompts like "refactor the codebase" produce chaos with teams. Specific prompts like "Teammate A: refactor /src/api/auth.ts to use the new middleware pattern. Teammate B: update all tests in /src/tests/auth/ to match" produce clean results.

3. Use Keyboard Shortcuts

• Shift+Up/Down: Select a teammate to view or message
• Enter (on selected teammate): Open direct message to that teammate
• Shift+Tab: Toggle delegate mode

4. Monitor Token Usage

Agent Teams consume significantly more tokens than single sessions. Each teammate is a separate Claude instance with its own context window. A 4-teammate session easily uses 4-5x the tokens of a solo session. Budget accordingly.

5. Always Clean Up

Call TeamDelete when work is complete. Orphaned teammate sessions keep running and burning tokens. The lead should explicitly shut down all teammates before ending.

The Claude Code Agent Teams YouTube Explosion

Three major YouTube videos dropped within 24 hours covering Claude Code Agent Teams — from WorldofAI, Cole Medin, and AI Labs. This signals massive developer interest but also means search demand is about to spike. Most of that content covers basic setup. This guide focuses on the patterns and pitfalls you'll hit after the initial "wow" moment fades.

What's Coming Next for Claude Code Agent Teams

Claude Code Agent Teams is still experimental. Based on the GitHub issues and Anthropic's pace of development, expect:

• Delegate mode fix: The tool inheritance bug will likely be resolved soon
• Persistent teams: Currently, teams exist only within a session. Persistent teams across sessions would be transformative
• Better token efficiency: The current overhead is high. Anthropic is likely working on context sharing optimizations
• SDK integration: The Claude Agent SDK already supports team operations programmatically. Expect deeper integration with CI/CD pipelines

Claude Code Agent Teams: Frequently Asked Questions

How do I enable Agent Teams in Claude Code?

Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 or add it to your Claude Code settings.json under the env key. The feature requires Claude Code 2.1 or later and works with Opus 4.6.

What's the difference between sub-agents and Agent Teams?

Sub-agents run inside your main session, do focused work, and report results back — they can't communicate with each other. Agent Teams creates independent sessions with their own context windows that can message each other directly through a mailbox system and coordinate via a shared task list.

How many teammates should I spawn?

Start with 2-3 for your first projects. Each teammate is a separate Claude instance consuming its own tokens. A team of 4 teammates uses roughly 4-5x the tokens of a single session. Scale up only when you've confirmed the coordination overhead is worth it for your specific task.

Does AGENTS.md work with Agent Teams?

AGENTS.md is even more critical with Agent Teams than with solo sessions. Each teammate reads it independently, so it must be explicit about file ownership, code standards, and coordination rules. Add a "File Ownership" section that maps directories to specific teammate roles to prevent merge conflicts.

Is delegate mode or plan mode better?

It depends on team size and task complexity. Plan mode works well for small teams (2-3) where the lead's direct contributions add value. Delegate mode (Shift+Tab) is better for larger teams (4+) where the lead should focus on coordination. Note that delegate mode currently has a known bug with tool access inheritance — check the issue tracker for updates.