Agent Teams — Coordinated Parallel Sessions

Agent teams coordinate multiple full Claude Code instances: one lead session spawns teammates that share a task list, message each other directly, and work in parallel. Unlike subagents (which only report back to the caller), teammates collaborate.

Experimental, disabled by default. Enable via settings:

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

Subagents vs Agent Teams

	Subagents	Agent teams
Context	Own window; result returns to caller	Own window; fully independent
Communication	Report to main agent only	Teammates message each other
Coordination	Main agent manages everything	Shared task list, self-claiming
Token cost	Lower	Much higher (each teammate = full instance)
Best for	Focused work where only the result matters	Work needing discussion/debate

Start a Team

Just describe it:

I'm designing a CLI tool that tracks TODO comments across a codebase.
Spawn three teammates: one on UX, one on architecture, one playing
devil's advocate.

The lead creates tasks, spawns teammates, synthesizes results.

Driving the Team

• Agent panel (below prompt input): ↑/↓ select teammate, Enter view + message directly, Esc interrupt, x stop, Ctrl+T toggle task list
• Display modes (teammateMode setting or --teammate-mode): in-process (default, any terminal) or split panes via tmux/iTerm2 (auto/tmux/iterm2)
• Models: “Use Sonnet for each teammate” or set Default teammate model in /config. Teammates inherit the lead’s effort level; their model/fast-mode is fixed at spawn
• Plan approval: “Require plan approval before they make changes” — teammate stays read-only until the lead approves its plan
• Reusable roles: “Spawn a teammate using the security-reviewer agent type” (uses your subagent definitions)
• Quality gates: hooks TeammateIdle, TaskCreated, TaskCompleted (exit code 2 = block + feedback)

Task List Mechanics

Tasks: pending → in progress → completed, with dependencies. Lead assigns explicitly, or idle teammates self-claim the next unblocked task. File locking prevents claim races. Stored in ~/.claude/tasks/<session-name>/; team config in ~/.claude/teams/<session-name>/config.json.

Permissions: teammates start with the lead’s permission mode; their prompts bubble up to the lead. A teammate can’t approve permissions or relay denied actions.

Best Practices

1. Start with research/review, not parallel implementation
2. 3–5 teammates, ~5-6 tasks each — beyond that, coordination eats the gains
3. One teammate per file area — parallel edits to the same file = overwrites
4. Spawn prompts need full context — teammates get CLAUDE.md but not the lead’s conversation
5. Monitor and steer; tell the lead to “wait for teammates to finish” if it starts doing the work itself

Known Limitations

• /resume doesn’t restore in-process teammates (tell lead to respawn)
• One team per session; no nested teams; lead is fixed
• Task status can lag — nudge if stuck
• Split panes don’t work in VS Code terminal / Windows Terminal

Real Case: Adversarial Bug Hunt

Users report the app exits after one message instead of staying connected.
Spawn 5 teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update findings.md with whatever consensus emerges.

Why it works: sequential investigation anchors on the first plausible theory. Independent investigators actively disproving each other converge on the actual root cause.

Real Case: Three-Lens PR Review

Spawn three teammates to review PR #142:
- one focused on security implications
- one checking performance impact
- one validating test coverage
Have them each review and report findings.

🧠 Quick Recall

• Trick: “Subagents report; teammates talk.”
• Sizing: 3–5 teammates, 5–6 tasks each.

👨‍🏫 Teach It

• Show: the adversarial bug-hunt prompt — theories disproving each other is the wow moment.
• They’ll trip on: two teammates editing one file — assign file ownership up front.

---

Learning path: ⬅ 31-worktrees.md · Index · ➡ 33-headless-and-scripting.md