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

Agent Teams: Roles & Handoffs

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

Specialized team patterns. Split scope, define handoffs, prevent collisions. Each teammate is a full instance with peer-to-peer messaging.

Subagents vs Agent Teams

These are not the same thing. Most people confuse them.

Subagents

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

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

How to Enable Agent Teams

Agent teams require an experimental flag. The API may change without warning in future releases.

• 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

How Agent Teams Actually Work

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

Actual Prompts That Work

The key pattern: define each teammate's role, scope, and the lead's coordination responsibility.

Why this works: Each teammate has a clear scope. Teammate C's adversarial role forces the others to defend their findings. The lead synthesizes; it does not do the work itself.

The peer communication matters here. Teammate A shares API contracts with B directly. Teammate C reviews both in real time. This is something subagents cannot do.

This is not about code. Agent teams work for strategic decisions too. Each teammate brings a perspective that challenges the others. The lead forces synthesis.

Moving Between Teammates

Once your team is running, you need to know how to talk to each member.

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

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

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

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

The Task List

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

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

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

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

Teams vs Subagents: When to Use Which

Click through the questions to get a recommendation.

What Agent Teams Actually Cost

No sugarcoating. Each teammate is a full Claude instance. A 4-person team costs roughly 4x a single session.

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.

5 Ready-to-Use Team Configurations

Copy, adapt to your codebase, run. Each is a complete prompt.

This is where teams shine over subagents. The debate step. Teammates challenging each other's conclusions produces better results than any individual investigation.

Quiz: Agent Teams

Test what you learned.

don't miss what's next.

playbooks, templates, and tools that actually save you hours. straight to your inbox. no spam. unsubscribe anytime.

Want this running in your business, not just your terminal? Our Claude Code development agency ships it for you, or book a free consultation to scope your setup.

Day 36: Agent Swarms: Coordinate Multiple Agents

Day 38: Context Engineering Mastery