Claude Code Agent Teams: Parallel Development with Multiple AI Instances

#Beyond Single-Agent Coding

Sub-agents are great for delegation — send a task out, get results back. But they have a limitation: sub-agents can only report to the main session. They can't talk to each other.

For complex features that span multiple layers — frontend, backend, database, tests — you sometimes need agents that coordinate directly. One agent building the API routes while another handles the React components, both aware of what the other is doing.

That's what Agent Teams do. Multiple Claude Code instances running in parallel, sharing a task list, claiming work, and communicating with each other.

#When to Use Agent Teams

Agent Teams add coordination overhead. They're worth it when:

Strong use cases:

• Research and review — multiple agents investigate different aspects simultaneously, then share findings
• New features with clear boundaries — frontend + backend + tests, each owned by a different agent
• Debugging with competing hypotheses — agents test different theories in parallel
• Cross-layer changes — auth system touches routes, middleware, models, and tests

Skip Agent Teams when:

• Tasks are sequential (agent B needs agent A's output)
• Changes are in the same file (merge conflicts)
• The work is simple enough for one session
• You're on a tight token budget

Rule of thumb: If you'd split the work across 2-3 human developers working in parallel, Agent Teams make sense. If one developer would handle it serially, use sub-agents or a single session.

#Enabling Agent Teams

Add the experimental flag to your settings or environment:

#Via Environment Variable

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true
claude

#Via settings.json

{
  "experiments": {
    "agentTeams": true
  }
}

#Starting Your First Team

Once enabled, you can start a team naturally:

"I need to add user authentication to this app. Start a team: one agent for the API routes and middleware, another for the frontend login/signup components, and a third for the database schema and migrations."

Or use the slash command:

/team start 3

This starts 3 teammate sessions. The main session becomes the team lead — it coordinates work, assigns tasks, and synthesizes results.

#How Teams Organize

1. Team lead breaks the request into a shared task list
2. Teammates claim tasks from the list
3. Each teammate works in its own context window with full tool access
4. Teammates communicate directly when they need to coordinate
5. Team lead monitors progress and synthesizes the final result

#Interacting with Teammates

You can talk to teammates directly without going through the lead:

# Navigate between teammates
Shift+Down    # Cycle through teammate sessions
# Send a message to a specific teammate
/team message 2 "Use the User model from src/models/user.ts for the auth routes"

#Display Modes

Agent Teams support different display modes for managing visual complexity:

• Full — see all teammate outputs in real-time
• Compact — see status summaries, expand on demand
• Lead only — see only the team lead's coordination messages

#Practical Example: Adding a Feature

Let's walk through a real scenario. You're adding a comments system to a blog app.

#Step 1: Describe the Feature

"Add a comments system to the blog. Users can post comments on articles, edit their own comments, and admins can delete any comment. Start a team of 3."

#Step 2: Team Lead Creates Task List

The lead automatically breaks this into tasks:

Task List:
[ ] Agent 1 — Database: Comment model, migrations, seed data
[ ] Agent 1 — API: CRUD routes for comments (/api/comments)
[ ] Agent 2 — Frontend: CommentSection component, CommentForm, CommentList
[ ] Agent 2 — Frontend: Edit/delete UI with permission checks
[ ] Agent 3 — Tests: API route tests, component tests, E2E test
[ ] Agent 3 — Tests: Permission edge cases (non-owner edit, admin delete)

#Step 3: Agents Work in Parallel

• Agent 1 creates the Prisma model, runs npx prisma migrate dev, builds the API routes
• Agent 2 builds React components — it messages Agent 1 to confirm the API response shape
• Agent 3 starts writing test scaffolding — it watches Agent 1 and 2's progress to test against real code

#Step 4: Lead Synthesizes

When all agents finish, the team lead:

• Verifies no merge conflicts
• Runs the full test suite
• Reports a summary of all changes

#Agent Team Configuration

#Custom Team Definitions

For recurring team structures, define them in .claude/teams/:

---
name: full-stack-feature
description: Frontend, backend, and test agents for new features
agents:
  - name: backend
    model: opus
    focus: "API routes, database, middleware"
  - name: frontend
    model: sonnet
    focus: "React components, UI, client-side logic"
  - name: testing
    model: sonnet
    focus: "Unit tests, integration tests, E2E tests"
---
When building a new feature:
1. Backend agent owns the data model and API layer
2. Frontend agent owns the UI components and client state
3. Testing agent writes tests against both layers
4. All agents communicate through the shared task list
5. Backend agent should commit schema changes first so others can reference them

#Model Mixing

Different teammates can run different models. Use cheaper models for simpler roles:

• Opus for the lead and complex implementation
• Sonnet for frontend work and testing
• Haiku for a dedicated code review teammate

This keeps costs manageable while still leveraging parallelism.

#Best Practices

#1. Clear Boundaries

Each teammate should own distinct files or directories. Overlapping file ownership causes merge conflicts and wasted tokens.

Good:

• Agent 1: src/api/, prisma/
• Agent 2: src/components/, src/app/
• Agent 3: __tests__/, cypress/

Bad:

• Agent 1 and Agent 2 both editing src/lib/utils.ts

#2. Share Interfaces, Not Implementation

When agents need to coordinate, have them agree on interfaces first:

Agent 1 → Agent 2: "The POST /api/comments endpoint accepts { articleId: string, body: string } and returns { id, body, author, createdAt }"

This is cheaper than Agent 2 reading Agent 1's entire implementation.

#3. Use the Lead for Conflict Resolution

If teammates disagree or create conflicting changes, let the team lead resolve it. Don't try to have teammates negotiate directly — it burns tokens fast.

#4. Kill Stuck Agents

If a teammate is spinning (exploring endlessly, repeating the same error), kill it:

Ctrl+F    # List and kill background agents

Better to restart with clearer instructions than let a stuck agent burn through your context and budget.

#5. Start Small

Begin with 2 agents, not 5. More agents means more coordination overhead and more token usage. Scale up only when you've confirmed the work can genuinely be parallelized.

#Known Limitations

Agent Teams are experimental. Be aware of:

• Session resumption — team sessions may not resume cleanly after a restart
• Task coordination — occasionally agents claim the same task or miss coordination signals
• Shutdown behavior — killing the lead may leave teammate processes running
• Token usage — a 3-agent team uses roughly 3-5x the tokens of a single session (not 3x, because of coordination overhead)
• Git conflicts — agents editing the same files will create conflicts that need manual resolution

#Agent Teams + OpenClaw

When running Claude Code through OpenClaw's ACP bridge:

• Agent Teams run entirely within Claude Code — OpenClaw sees one ACP session
• If you need OpenClaw-visible multi-agent coordination, use OpenClaw's own sessions_spawn with multiple ACP sessions
• For most users: let Claude Code handle the internal parallelism, let OpenClaw handle the orchestration and chat delivery

The two multi-agent systems work at different levels. OpenClaw orchestrates across tools and channels. Claude Code Agent Teams parallelize within a single coding task.

#Getting Started

1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true
2. Start with a 2-agent team on a feature with clear file boundaries
3. Watch the coordination — adjust task descriptions if agents overlap
4. Scale to 3 agents once you're comfortable with the pattern
5. Create custom team definitions for your recurring workflows

Agent Teams are the highest-leverage feature in Claude Code for large projects — but they're also the most expensive. Use them strategically on work that genuinely benefits from parallelism.

For advanced team configurations, cross-repo coordination, and cost optimization strategies, check out the premium guides on ClawDocx.