Day 25

Agent Teams — Multiple Claude Sessions Talking to Each Other

Day 24 Day 26

Claude Code // Day 25

Multiple full Claude sessions.
Talking to each other.
Self-coordinating.

Experimental Feature StatusPeer-to-Peer Messaging ModelShared Task List Coordination Layer

01 // Critical Distinction

Subagents vs Agent Teams

These are not the same thing. Most people confuse them. Here is the difference that matters.

Subagents

Stable Feature

Parent

↓ ↓ ↓

Worker AWorker BWorker C

dashed red = no communication

Fan-out from one parent session
Return results only, no peer comms
Parent decides, children execute
Cheaper: lightweight spawned processes
One-way: parent sends task, child returns result
Good for parallelizable, independent tasks

Agent Teams

Experimental

Lead

↓ ↓ ↓

Teammate ATeammate BTeammate C

↔ peer-to-peer messaging ↔

dashed green = peer-to-peer messaging

Each teammate is a full Claude session
Talk to each other directly (peer-to-peer)
Self-coordinate through shared task list
Can challenge, review, build on each other's work
Higher cost: each teammate = full instance
Good for complex, interdependent work

02 // Setup

How to Enable Agent Teams

Agent teams require an experimental flag. This means the feature is functional but the API may change without warning in future releases.

settings.json

// In your settings.json (project or user-level) { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

What "experimental" means

1.The feature works and is usable in production workflows

2.The API surface (env var name, spawning syntax) may change

3.You need to explicitly opt in — it will not activate by default

4.Cost implications are real: each teammate is a full Claude instance

03 // The Architecture

How Agent Teams Actually Work

This is the mental model. You talk to the lead session. The lead assigns work to teammates. Teammates talk to each other. Everyone sees the shared task list.

You

Your Terminal

Primary interface

↓—

Lead Session

Coordinator

Orchestrates work, reports to you

↙

↓

↘

Teammate A

Backend

Full Claude session

Teammate B

Frontend

Full Claude session

Teammate C

Tests

Full Claude session

Shared Task List

1. Build API routes[ A ]

2. Create components[ B ]

3. Write test suite[ C ]

4. Integration tests[ -- ]

Lead assignsPeer-to-peerActive session

04 // Spawning a Team

Actual Prompts That Work

The key pattern: define each teammate's role, scope, and the lead's coordination responsibility. Be explicit about who does what.

Example 1: Research Team

Example 2: Full-Stack Feature Build

Example 3: Security Audit

Example 4: Board of Directors (Business Use)

05 // Navigation

Moving Between Teammates

Once your team is running, you need to know how to talk to each member and monitor their work.

Cycle Between Teammates

Shift+Down

Press Shift+Down to cycle through teammates. Each press moves focus to the next active session.

Direct Message Any Teammate

You can message any teammate directly. Not just the lead. Useful when you want to give specific instructions or override a direction.

Split Mode (tmux)

Each teammate can run in its own tmux pane. See all sessions simultaneously. Best for monitoring parallel work.

Combined Mode

All teammates share the lead terminal. Output interleaved. Simpler setup, harder to follow with more than 2 teammates.

06 // Shared State

The Task List

The shared task list is the coordination layer. It is visible to every teammate. It is how agents self-organize without constant human intervention.

Shared Task List

1.Design database schema[ A ]done

2.Build API endpoints[ A ]working

3.Create React components[ B ]working

4.Write unit tests[ C ]assigned

5.Integration tests[ -- ]unclaimed

6.Final review[ -- ]unclaimed

Lead Creates

The lead session defines and populates the task list based on the overall goal.

Teammates Self-Assign

Unclaimed tasks can be picked up by any teammate. Self-organizing when roles overlap.

Visible to All

Every teammate sees the full list. No information silos. Everyone knows who is doing what.

07 // Decision Framework

Teams vs Subagents: When to Use Which

Click through the questions to get a recommendation.

Question 1 of 4

Do workers need to communicate with each other?

08 // Cost Reality

What Agent Teams Actually Cost

No sugarcoating. Each teammate is a full Claude instance. A 4-person team costs roughly 4x what a single session costs. Here is when that is worth it.

The Math: 1 teammate = 1 full Claude session (same context window, same token usage, same cost per token). A 4-person team running for 30 minutes each = cost of 4 individual 30-minute sessions running in parallel.

Use Case	Complexity	Peer Comms Needed?	Verdict
Parallel file edits (independent)	Low	No	Subagents
Code generation + tests (same feature)	Medium	Nice to have	Either
Full-stack feature (API + UI + tests)	High	Yes	Teams
Security audit (multiple domains)	High	Yes	Teams
Linting / formatting batch	Low	No	Subagents
Architecture review	High	Critical	Teams
Data migration scripts	Medium	Minimal	Subagents
Competing hypotheses (debug)	High	Essential	Teams