← All guides

WorkflowSetup

Claude Code Agent Teams: What They Are and How to Set One Up

By Neo Zino - builder of ClockedCode·Updated July 15, 2026·9 min read

What Claude Code agent teams actually are, how to turn on the experimental flag, a real worked example, and when they beat reaching for a single subagent.

One environment variable is all that separates a normal Claude Code session from a coordinated team of them: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. Flip it on and one session becomes a team lead that can spawn teammates, each a full Claude Code instance with its own context window, that claim work off a shared task list and message each other directly instead of only reporting back to you. It's the setting I get the most questions about out of everything in the ClockedCode master prompt, so here's the walkthrough I wish existed when I first turned it on.

TL;DR: Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" in the env object of settings.json, then describe a task and the roles you want in plain language - Claude spawns teammates, populates a shared task list, and synthesizes their findings when they finish. The core difference from a subagent is communication: subagents only report back to the main agent, teammates message each other directly and self-coordinate off the shared list. Start with 3-5 teammates; token cost scales with each one you add, so save teams for work that genuinely benefits from parallel, discussable exploration, not routine sequential edits.

What are Claude Code agent teams?

An agent team is a group of Claude Code sessions working the same problem, coordinated rather than isolated. One session, the one you're already talking to, becomes the team lead the moment it spawns a first teammate. Each teammate gets its own full context window, loads the same project CLAUDE.md, MCP servers, and skills a regular session would, and receives a spawn prompt from the lead describing its job. From there teammates work independently, claim tasks off a list every agent can see, and message each other by name when they need to share a finding or ask a question.

The mental shortcut that made this click for me: a subagent is a phone call your main session makes and hangs up on when the answer comes back. A teammate is a coworker in the room who can also talk to your other coworkers without routing everything through you.

How do I enable agent teams?

Agent teams ship disabled, and the docs are blunt about why: without the flag, no team directory gets written at session start and Claude will not spawn or propose a teammate no matter how the task is phrased. Turn it on in settings.json:

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

That is the exact line ClockedCode's own master prompt writes into a fresh setup, under an "Enable agent teams" step, so if you've run the ClockedCode install once already, this is on. If you're hand-editing settings.json instead, the free settings.json generator adds this flag alongside your permission rules and hooks without you needing to merge JSON by hand.

One thing worth knowing if you read an older writeup: before v2.1.178, turning the flag on wasn't enough by itself - you had to ask Claude to create and name a team first, using tools called TeamCreate and TeamDelete. Both tools are gone now. Spawning a teammate today needs no setup step, and cleanup happens automatically when the session ends. If a post you find still talks about naming a team before use, it predates that change.

A worked example, with a real teammate role

After enabling the flag, you don't run a special command, you just ask for teammates in the same sentence as the task:

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.

Claude reads that, spawns three teammates, and populates a task list under ~/.claude/tasks/ with one review lens per teammate. Each teammate messages the lead through its own mailbox file (~/.claude/teams/{team-name}/inboxes/{agent-name}.json) when it finishes, and the lead synthesizes the three findings once every teammate goes idle.

The detail I actually use day to day: you can hand a teammate an existing subagent definition instead of writing its role from scratch. ClockedCode ships a security-reviewer subagent, so on a real repo I'll spawn the team with:

Spawn a teammate using the security-reviewer agent type to audit the
auth module, plus a second teammate to write tests for whatever it finds.

The teammate inherits that subagent's tool allowlist and its system prompt gets the definition's instructions appended, so a role you already trust for delegated subagent calls works the same way inside a team. SendMessage and the task tools stay available to it regardless of what the subagent's own tools field restricts.

For watching the team work: the default display is in-process, meaning every teammate shows up as a row in the agent panel under your prompt, and the up and down arrows plus Enter open a teammate's transcript to read or message it directly. If you want each teammate visibly running in its own pane instead, set "teammateMode": "auto" in settings.json (needs tmux, or iTerm2 with the it2 CLI installed) or pass --teammate-mode auto for a single session.

Agent teams vs subagents

The row that decides which one to reach for is communication, not cost. If the work is a focused question with one right answer, a subagent that reports back and disappears is cheaper and simpler. If the value is in teammates comparing notes, like three competing debugging theories trying to disprove each other, or a security review, a performance pass, and a test-coverage pass happening side by side, agent teams earn the extra tokens because the discussion itself is the point.

How big should a team be?

Bigger isn't automatically better here. Every teammate you add is a separate Claude session burning its own context window, and coordination overhead (messaging, task claiming, synthesizing) grows with headcount too. If a task genuinely splits into fifteen independent pieces, three teammates working through five each is a better shape than fifteen teammates each doing one thing and mostly idling between messages.

TeammateIdle, TaskCreated, and TaskCompleted are also real hook events if you want to enforce a rule, like blocking a task from being marked complete until tests actually pass, rather than trusting the team to self-police.

When agent teams are the wrong tool

An honest list, because the coordination overhead is real:

• Same-file edits. Two teammates editing the same file is a guaranteed overwrite. Split by file or module, not by aspect of the same file.
• Sequential work with hard dependencies. If task 2 can't start until task 1 finishes and task 3 needs both, you're paying for parallelism you can't use. A single session or a chain of subagent calls is faster and cheaper.
• Anything routine. Formatting a file, writing one test, answering a quick factual question - these don't need a second full Claude session and its context window.
• Long unattended runs. The docs list session resumption with in-process teammates as a known gap: /resume won't restore them, and a lead that comes back from a resumed session may try to message teammates that no longer exist. Check in on a running team rather than walking away for hours.

FAQ

What are Claude Code agent teams?

Agent teams let multiple Claude Code sessions coordinate on one piece of work. One session becomes the team lead, spawns teammates, and each teammate runs in its own full context window, claims work off a shared task list, and messages other teammates directly instead of only reporting back to the lead. That direct communication is the whole difference from a subagent.

How do I enable Claude Code agent teams?

Add CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS with a value of "1" to the env object in settings.json. They are off by default and marked experimental - without the flag, no team gets set up at session start and Claude never spawns or proposes a teammate.

What's the difference between agent teams and subagents?

A subagent runs inside your session, does its task, and reports the result back to the main agent - it never talks to another subagent. A teammate is a fully separate Claude Code session that claims tasks off a shared list and can message any other teammate directly. Subagents are cheaper and simpler for a focused task where only the result matters. Agent teams cost more tokens but earn it back on work that genuinely benefits from discussion, like competing debugging hypotheses or a multi-angle review.

How many teammates should I spawn?

The docs suggest starting with 3 to 5 teammates and roughly 5 to 6 tasks per teammate for most workflows. Beyond that range, coordination overhead - messaging, task claiming, synthesizing results - tends to grow faster than the speedup, and three focused teammates often outperform five scattered ones.

Do agent teams cost more than a single session?

Yes, meaningfully more. Each teammate is a separate Claude instance with its own context window, so token usage scales roughly with the number of active teammates rather than staying flat like a subagent call does. It is worth it for research, review, and genuinely parallel feature work; for routine, sequential tasks a single session stays cheaper and just as fast.

Start with one review, not a whole sprint

The fastest way to get a feel for agent teams is the least ambitious one: point three teammates at a single PR with three different lenses and watch how they actually coordinate before handing them anything bigger. Once that rhythm makes sense, moving up to feature work split across teammates is a small step, not a leap. This is exactly the kind of setting ClockedCode flips on for you by default, along with the subagents that give a team something real to spawn from instead of a blank role description.