Agent Teams in Claude Code: several Claude sessions working like a real team

Subagents let Claude hand work to an “assistant” and get a result back. Agent Teams go one step further: several Claude Code sessions work like a real team — with a lead, a shared task board, and members who message each other directly to share findings and challenge one another. It’s experimental, but well worth trying for reviews, debugging and large features.

Enabling it

Agent Teams are experimental and off by default. Turn them on with an environment variable, in your shell or in settings.json:

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

Two things to know once enabled:

• While the feature is on, any subagent Claude names when spawning it launches as a teammate — so teams can form even when you didn’t ask for one. To go back to plain subagents, set the variable to 0 (it takes effect immediately, no new session needed).
• Teammates are only spawned in interactive sessions. In claude -p or the Agent SDK, Claude doesn’t create teammates.

Team architecture

Teammates automatically load project context like a normal session (CLAUDE.md, MCP servers, skills) and receive a spawn prompt from the lead — but they do not inherit the lead’s conversation history.

Subagents or an Agent Team?

For sequential work, same-file edits or heavy dependencies, a single session or subagents are more effective.

Starting your first team

No extra configuration — describe the task and the line-up in plain language:

We're designing a CLI that tracks TODO comments in a codebase.
Create three teammates to look at it from different sides:
UX, technical architecture, and a critic who challenges both.

You can set the size and model too: “Create 4 teammates to refactor these modules in parallel, all on Sonnet.” If Claude creates subagents instead of a team, ask again and explicitly request an “agent team”.

Controlling the team

• In-process mode (default): all teammates run inside your main terminal. Use ↑/↓ in the agent panel to select a teammate, Enter to open its session and message it, Esc to clear the selection or interrupt its current turn, x to stop it, and Ctrl+T to toggle the task list.
• Split-pane mode: each teammate gets its own pane; requires tmux or iTerm2 (with the it2 CLI). Enable with "teammateMode": "auto" in ~/.claude/settings.json or claude --teammate-mode auto. Not supported in VS Code’s integrated terminal, Windows Terminal or Ghostty.

Assigning and claiming tasks

The lead creates tasks and teammates work through them. Tasks can depend on others — a blocked task isn’t self-claimed until its dependencies complete. The lead can assign tasks explicitly, or teammates who finish pick up the next unassigned, unblocked task. Claiming uses file locking, so two teammates can’t grab the same task.

Make teammates plan first

For risky work, put the lead in plan mode first, then ask: “Spawn an architect teammate to refactor the authentication module.” That teammate stays read-only until its plan is ready, sends a plan-approval request to the lead, and only starts editing once approved.

Quality gates with hooks

Shutting down

Refer to the teammate by name: “Ask the researcher teammate to shut down.” It can approve or decline with an explanation. Team config directories are cleaned up when the session ends; the task list stays on disk according to cleanupPeriodDays.

Three scenarios worth trying

1. Parallel PR review

Create three teammates to review PR #142:
- one looking only at security
- one measuring performance impact
- one checking test coverage
Each reports findings; then summarise.

A single reviewer tends to fixate on one kind of issue; separate lenses get all three aspects examined thoroughly at once.

2. Debugging with competing hypotheses

Users say the app disconnects after the first message.
Create 5 teammates, each testing a different hypothesis. Have them message
each other and try to knock down the other theories, debate-style.
Write the agreed conclusion into the findings doc.

Sequential investigation tends to anchor on the first theory. When teammates actively try to disprove each other, the surviving theory is much more likely to be the real root cause.

3. Cross-layer features

Frontend, backend and tests are each owned by a different teammate, coordinating through the task list and messages.

Operating lessons

• Size: start with 3–5 teammates. Tokens scale linearly with headcount and coordination overhead grows too; three focused teammates often beat five scattered ones.
• Task size: each task should produce a clear deliverable (a function, a test file, a review). Around 5–6 tasks per teammate lets the lead reassign work when someone gets stuck.
• Avoid file conflicts: two teammates editing the same file overwrite each other — split work by file ownership.
• Rich spawn prompts: spell out folders, stack and evaluation criteria, since teammates can’t see the lead’s chat history.
• Make the lead wait: if the lead starts doing the work itself, tell it to wait until the teammates have finished their tasks.
• Fewer permission prompts: teammate permission requests bubble up to the lead — pre-approve common commands before spawning.
• New to teams? Start with non-coding work (reviews, library research, bug investigation) to see the value before attempting parallel implementation.

Current limitations

• /resume and /rewind don’t restore in-process teammates.
• Task status can lag — a teammate forgetting to mark a task done blocks its dependants.
• One team per session; no nested teams; the lead is fixed for the session’s lifetime.
• No per-teammate permission modes at spawn time (you can only change them afterwards).

How to apply it

• Developers: Try it on a big PR review before merging — three teammates, three lenses, the lead synthesises. No code changes, so low risk.
• Tech Leads: Define roles (security-reviewer, test-runner) as subagents in .claude/agents/; when spawning a team, just say “use the security-reviewer agent type”.
• PMs: Treat an agent team like a small squad: lead = Tech Lead plus Scrum Master, task list = board, the TaskCompleted hook = Definition of Done. Principles like independent work items and WIP limits still apply.