Agent Teams & Communication

What You’ll Learn

Agent Teams are Claude Code’s experimental mode for sustained collaboration among multiple independent sessions. This session focuses on the public operating model:

• one lead coordinates the team;
• teammates work in separate context windows;
• a shared task list tracks ownership and dependencies;
• a mailbox carries direct messages between agents.

Agent Teams are experimental and disabled by default. The workflow below is verified against the official documentation on July 20, 2026.

The Public Team Model

Component	Responsibility
Team lead	Spawns teammates, coordinates work, assigns tasks, and synthesizes the result
Teammates	Independent Claude Code sessions that investigate or implement bounded work
Shared task list	Holds pending, in-progress, and completed tasks, including dependencies
Mailbox	Delivers messages between the lead and teammates, or directly between teammates

A teammate receives the project context it would normally load, such as CLAUDE.md, skills, and MCP servers, plus its spawn prompt. It does not inherit the lead’s conversation history. Put every task-specific fact needed for success in the spawn prompt or a message.

Agent Teams vs. Subagents

Use a subagent when a focused worker can return one result to its caller. Use an Agent Team when workers need to exchange findings, challenge one another, claim work, or stay independently addressable.

	Subagent	Agent Team teammate
Context	Separate context	Separate, independent session
Communication	Reports to caller	Can message lead and teammates
Coordination	Main agent delegates	Shared task list supports self-coordination
Cost	Lower	Higher; every teammate consumes its own context

Enable Agent Teams

Set the experimental flag in your environment or settings:

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

Then describe the team and its boundaries in natural language:

Create an agent team with three teammates:
- researcher: map the current authentication flow
- reviewer: look for security and permission risks
- tester: identify missing tests

Give each teammate a separate task. Ask them to share evidence with one another,
then wait for all tasks to finish before synthesizing the result.

The first spawned teammate forms the team and the current session becomes the lead. In current versions there is no public TeamCreate or TeamDelete tool to script around.

Coordinate Through Tasks and Messages

The lead can assign a task explicitly, while an idle teammate can claim an unassigned, unblocked task. Dependencies keep work pending until prerequisites are complete.

Use messages for information that changes another agent’s work:

Tell reviewer that researcher found token parsing in src/auth/token.ts.
Ask tester to validate the same boundary and report the failing command.

Messages are delivered automatically. The task list records work state; it is not a substitute for explaining acceptance criteria, file ownership, or evidence.

A Reliable Operating Pattern

1. Split work into independent deliverables with distinct file ownership.
2. Give each teammate the relevant paths, constraints, and definition of done.
3. Put dependencies in the shared task list instead of relying on timing.
4. Ask teammates to send evidence, not only conclusions.
5. Wait for all active work to finish, then have the lead reconcile conflicts and verify the combined result.

Start with three to five teammates only when parallelism is worth the coordination and token cost. Sequential work, tightly coupled tasks, and same-file edits are usually better handled in one session.

Lifecycle and Limits

• You can steer a teammate directly from the in-process agent panel or its split pane.
• Permission requests still require the user’s authority; one agent cannot approve another agent’s denied action.
• Ask the lead to shut down a teammate gracefully when its work is finished.
• Team runtime state is managed by Claude Code and cleaned up when the session ends. Do not build workflows around private files or undocumented schemas.
• Session resumption, coordination, and shutdown still have documented experimental limitations.

The durable contract is the behavior above: lead, teammates, shared tasks, and messaging. Internal filenames and storage layouts are implementation details unless the official reference explicitly says otherwise.

Official Sources

• Orchestrate teams of Claude Code sessions
• Create custom subagents

Next Session

Next, turn collaboration into an explicit protocol: ownership, evidence, handoff, and completion rules.