Guide / Claude Code

Claude agent teams: a guide to Claude Code agent teams

Claude agent teams let a lead coordinate independent coding sessions. Use Claude Code agent teams when work benefits from parallel investigation, separate file ownership and discussion between teammates. This guide covers setup, a practical feature split, costs and a shared Atoll board.

Experimental feature. Official sources checked 25 October 2026.

Enable teams Try a feature split Connect the board Sources

The model

One lead, independent teammates

The lead is the main Claude Code session. It starts teammates, coordinates assignments and combines their results. Each teammate is a separate Claude Code instance with its own context window. Teammates can communicate directly, and you can message one without routing every question through the lead.

In sessions with Task tools, the shared task list records pending, in-progress and completed work. Dependencies prevent a task from being claimed until its prerequisites finish. Agents without those tools coordinate through messages. Treat the list as working session state: check the underlying result before accepting a completion claim.

Good candidates include independent review lenses, investigating competing explanations for a bug, and building separate modules against an agreed interface. A tightly sequential change or several edits to the same file usually gains little from a team. Parallel execution still needs integration and review time.

Setup

Enable the experiment explicitly

Agent teams are disabled by default. To enable them for a shell-launched interactive session, set the environment variable to 1, then launch Claude:

Shell

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

Alternatively, add this env entry to your Claude Code settings.json:

settings.json / enable teams

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

Ask for an agent team in plain language and name the roles you need. Spawning teammates requires an interactive session: the -p non-interactive path, including Agent SDK sessions, does not spawn teammates. Enabling the flag can also turn ordinary named subagent delegation into teammates, subject to the documented fork and isolation exceptions. Set the flag to 0 when you want that behavior disabled, and check higher-precedence settings.

Display and limits

Start in one terminal

The default in-process mode needs no extra terminal setup. Select a teammate with the up and down arrows in the agent panel; press Enter to view its transcript and send a message. Split panes require tmux or iTerm2 with the it2 CLI. To select split panes when supported and fall back otherwise, set teammateMode in ~/.claude/settings.json:

settings.json / display mode

{
  "teammateMode": "auto"
}

You can also choose the mode for one session:

Shell / one-session display override

claude --teammate-mode auto

This flag is experimental and absent from claude --help. Split panes are unsupported in the VS Code integrated terminal, Windows Terminal and Ghostty. Keep the in-process default if your terminal setup is uncertain.

Plan for the current limits: one team per session, a fixed lead and no nested teams. /resume and /rewind do not restore in-process teammates. Task status can lag behind completed work, and shutdown waits for the current request or tool call. Save decisions and evidence outside the conversation before ending it; ask the lead to shut down teammates when finished.

Example

Split a feature by ownership

Agree on the contract before parallel edits begin. For saved report filters, the API and UI can have separate owners once request fields, response shape and permission behavior are clear. A reviewer can investigate risks while those owners build. Adapt this prompt to actual repository paths:

Example team prompt

Create an agent team to add saved report filters to this app.
First inspect the repository and agree on the filter data contract.
Then spawn three teammates:
- api: own the saved-filter API and persistence files only.
- ui: own the report filter components only; use the agreed contract.
- review: inspect the existing permission boundaries and propose
  acceptance cases. Do not edit implementation files.

Give each teammate the relevant paths, acceptance criteria and contract.
Do not let two teammates edit the same file. If a shared type must change,
keep that edit with the lead and tell both builders when it is ready.
Have api and ui exchange contract questions directly. Review reports
findings to the lead; the relevant owner fixes accepted findings.
Wait for teammates before integrating. Report changed files, checks,
remaining blockers and review findings. Do not merge or deploy.

Give each assignment enough context to stand alone: the issue, relevant paths, agreed interface, forbidden edits and required checks. Teammates load project instructions but do not inherit the lead’s conversation. If the API contract changes, pause the dependent UI work and communicate the decision before both sides implement incompatible assumptions.

Keep the team small and inspect progress. A blocked worker needs a concrete question or a narrower task. Adding workers to an unresolved shared-file conflict adds coordination work instead of removing the conflict.

Shared accountability

Keep humans and agents on one Atoll board

Claude’s local team list helps coordinate the session. Atoll gives the wider team a shared record of issues, owners, status and handoff comments. Start with the Atoll MCP setup guide and connect the hosted endpoint at https://atollhq.com/mcp. The remote HTTP configuration is:

.mcp.json / Atoll remote connection

{
  "mcpServers": {
    "atoll": {
      "type": "http",
      "url": "https://atollhq.com/mcp"
    }
  }
}

Complete OAuth sign-in through the client and authorize the Atoll agent profiles that may act. Call atoll_list_agent_profiles first; select a profile and pass its profile_ref on later calls. If multiple organizations are accessible, supply org_id too. A Claude teammate name does not automatically become an Atoll identity. Calls use the selected profile’s permissions.

Have the lead read the project’s issues with atoll_list_issues and confirm the parent issue’s acceptance criteria.
Use atoll_create_issue for the agreed API, UI and review work. Record file ownership and dependencies in the issue descriptions; assign only to existing, authorized Atoll members.
Use atoll_update_issue for status changes and atoll_add_comment for blockers, decisions and evidence. Have the lead reconcile these updates with the local team list.
At handoff, record changed paths, check results, review findings and remaining decisions. Mark work complete only after its acceptance criteria are met.

These are explicit tool calls, not automatic task-list synchronization. Keep source changes and CI reports in their owning systems and link the evidence from Atoll. For the broader workflow, see project management for AI coding agents and the agent project management model.

FAQ

Costs, context and subagents

How much do Claude Code agent teams cost?

There is no single fixed team price. Each teammate sends requests from its own context window, so usage grows with the number of active teammates and how long they work. Model choice and context size also matter. Use /usage to inspect usage; its API dollar estimate is not a subscription invoice. Start with a small, bounded task and compare the result and usage with a single-session run.

Do teammates share the lead’s conversation context?

Each teammate has its own context window. It loads project context such as CLAUDE.md, MCP servers and skills, and receives the lead’s spawn prompt. The lead’s conversation history does not carry over. Include the decision, relevant paths, constraints and expected output in each assignment instead of assuming the teammate saw an earlier discussion.

How are agent teams different from subagents?

Subagents delegate focused work within a session and return results to the caller. Agent teams coordinate separate Claude Code instances through direct messages and, where Task tools are available, a shared task list. Named subagents can also exchange messages, so messaging alone is not the distinction. Choose teams when the workers need ongoing discussion and coordination; use a subagent for a bounded investigation or summary.

Does connecting Atoll automatically sync Claude’s task list?

The workflow in this guide uses explicit Atoll MCP calls. Claude’s local team tasks and Atoll issues remain separate records. Ask the lead to create or update the corresponding Atoll issues and post evidence at handoff. A Claude teammate name does not create an Atoll member or select an authorized agent profile.

References

Official sources

Checked 25 October 2026. Claude Code’s experiment can change; compare these references with your installed version before adopting the workflow.

Connect your team’s board

Give the team a shared record.

Keep issues, decisions and review evidence in the same workspace as your human teammates.

Start free Connect through MCP