obsidian/wiki/claude-code/agent-teams.md

title	aliases	tags	sources	created	updated
Agent Teams — Orchestrate Multiple Claude Code Sessions	agent-teams claude-agent-teams multi-session-teams	claude-code multi-agent parallelism orchestration experimental	raw/Orchestrate teams of Claude Code sessions.md	2026-04-17	2026-04-17

Agent Teams

Agent teams let you coordinate multiple Claude Code instances working together. One session acts as team lead; the rest are teammates — independent sessions that communicate directly with each other via a shared task list and mailbox.

Experimental — requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json or env. Needs Claude Code v2.1.32+.

---

Enabling

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

---

Architecture

Component	Role
Team lead	Main session — spawns teammates, owns task list, synthesizes results
Teammates	Independent Claude Code instances with their own context windows
Task list	Shared work items; teammates claim and complete them (~/.claude/tasks/{team}/)
Mailbox	Async messaging between any two agents by name

• Team config stored at ~/.claude/teams/{team-name}/config.json — do not edit by hand
• Task claiming uses file locking to prevent race conditions
• Dependencies are managed automatically: blocked tasks unblock when their dependency completes

---

Agent Teams vs Subagents

	Subagents	Agent Teams
Communication	Report results to main agent only	Teammates message each other directly
Coordination	Main agent manages all work	Shared task list with self-coordination
Best for	Focused tasks where only result matters	Complex work requiring discussion/collaboration
Token cost	Lower	Higher (each teammate is a separate Claude instance)

Use wiki/claude-code/custom-subagents when workers only need to report back. Use agent teams when teammates need to share findings and challenge each other.

---

When to Use

Strong use cases (parallel exploration adds value):

• Research & review — multiple angles investigated simultaneously
• New modules — each teammate owns a separate piece
• Debugging with competing hypotheses — teammates test theories in parallel
• Cross-layer changes — frontend, backend, tests each owned by a different teammate

Avoid agent teams for:

• Sequential tasks
• Same-file edits
• Work with many interdependencies (use a single session or subagents instead)

---

Display Modes

Mode	How	Requires
in-process (default)	All teammates in one terminal; Shift+Down cycles through	Nothing
split-panes	Each teammate gets its own pane	tmux or iTerm2 + it2 CLI

Override in ~/.claude.json:

{ "teammateMode": "in-process" }

Or per session: claude --teammate-mode in-process

---

Control Patterns

Spawn a team (natural language)

Create an agent team: one teammate on UX, one on architecture, one as devil's advocate.

Specify teammates and models

Create a team with 4 teammates. Use Sonnet for each teammate.

Require plan approval before implementation

Spawn an architect teammate to refactor auth. Require plan approval before any changes.

Lead reviews → approves or rejects with feedback → teammate revises if rejected → implements when approved.

Direct teammate messaging

• In-process: Shift+Down to cycle, type to message, Enter to view session, Escape to interrupt, Ctrl+T for task list
• Split-pane: click into a pane

Shutdown & cleanup

Ask the researcher teammate to shut down
Clean up the team        # run after all teammates are stopped

Always run cleanup from the lead, not a teammate.

---

Quality Gates via Hooks

Hook	Trigger	Exit 2 =
TeammateIdle	Teammate about to go idle	Send feedback, keep teammate working
TaskCreated	Task being created	Block creation with feedback
TaskCompleted	Task being marked done	Block completion with feedback

See wiki/claude-code/overview for general hooks documentation.

---

Permissions & Context

• Teammates inherit the lead's permission settings at spawn time (including --dangerously-skip-permissions)
• Each teammate loads project context fresh: CLAUDE.md, MCP servers, skills — but not the lead's conversation history
• Include task-specific details in the spawn prompt
• Teammates can reference wiki/claude-code/custom-subagents by name for reusable roles

---

Best Practices

• Start with 3–5 teammates — balances parallelism with coordination overhead
• 5–6 tasks per teammate — prevents context-switching overload
• Break work by file ownership — two teammates editing the same file causes overwrites
• Begin with research/review tasks if new to agent teams (no code-conflict risk)
• Monitor and steer — don't let teams run unattended too long
• Tell the lead to wait if it starts implementing instead of delegating: "Wait for your teammates to complete their tasks before proceeding"

---

Limitations (Experimental)

• No session resumption for in-process teammates (/resume//rewind don't restore them)
• Task status can lag — may need manual nudge
• Shutdown can be slow (teammate finishes current request first)
• One team per lead session
• No nested teams — teammates cannot spawn their own teams
• Lead is fixed for the team's lifetime
• Split panes not supported in VS Code terminal, Windows Terminal, or Ghostty

---

Key Takeaways

• Agent teams are experimental and token-expensive — each teammate is a full Claude instance
• The core advantage over subagents: teammates communicate directly and share a task list with self-coordination
• 3–5 teammates, 5–6 tasks each is the recommended starting size
• The lead controls everything — spawning, task assignment, cleanup; never run cleanup from a teammate
• Use hooks (TeammateIdle, TaskCreated, TaskCompleted) to enforce quality gates automatically
• Best ROI on research, parallel review, and competing-hypotheses debugging — not sequential or same-file work

---

Sources

• raw/Orchestrate teams of Claude Code sessions.md
• Official docs: https://code.claude.com/docs/en/agent-teams