Claude Code Agent Teams: Setup, Commands, and Use Cases

What Are Claude Code Agent Teams?

Claude Code Agent Teams run several Claude Code sessions against one problem at once. One session leads, assigns work, and synthesizes results. The rest are teammates: independent sessions that message each other.

According to the Claude Code agent teams documentation, the feature is experimental and disabled by default, and the page currently describes behavior as of version 2.1.178. Two things separate it from every earlier parallelism option in Claude Code:

• Teammates address each other by name - a discovery made by one teammate reaches another without the lead relaying it, so no single context becomes the bottleneck for every insight.
• You can talk to any teammate yourself - open its transcript, redirect it, or ask it a follow-up question without going through the lead at all.

The practical effect is that a team can argue. Five teammates investigating five hypotheses can try to disprove each other, and the theory left standing is far more likely to be the real root cause than the first plausible answer a single session settles on. That is the capability you are buying with the extra tokens, and it is what separates the agent teams Claude Code ships today from ordinary parallel execution.

How Do Claude Code Agent Teams Work?

A team has four moving parts. Anthropic's agent teams documentation names them as the lead, the teammates, a shared task list, and a mailbox, and all four are ordinary files on your disk rather than a hosted service.

• Team lead - the main session you are typing in. It spawns teammates, creates tasks, and stays the lead for the life of the session. Leadership cannot be transferred to a teammate.
• Teammates - separate Claude Code instances. Each loads your project CLAUDE.md, MCP servers, and skills at spawn, exactly like a fresh session, plus the spawn prompt the lead gives it.
• Shared task list - work items with three states: pending, in progress, and completed. A task can depend on other tasks, and a pending task with unresolved dependencies cannot be claimed until they finish.
• Mailbox - a JSON file per agent at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Claude Code reports a message as sent only when the write to the recipient's mailbox file succeeds.

The team name is derived from your session, not chosen by you: it is the word session- followed by the first eight characters of the session ID. The team config lives at ~/.claude/teams/{team-name}/config.json and the task list at ~/.claude/tasks/{team-name}/.

Those two directories behave differently when the session ends. The team config directory is removed. The task list directory persists locally and is never uploaded, so a resumed session keeps its tasks, with retention governed by the same cleanupPeriodDays setting that controls session transcripts.

One detail worth internalizing before you build workflows on top of this: the team config holds live runtime state such as session IDs and terminal pane IDs. Editing it by hand or pre-authoring it does not work, because Claude Code overwrites your changes on the next state update. There is also no project-level equivalent, so a .claude/teams/teams.json in your repo is treated as an ordinary file, not configuration.

If the idea of independent agents coordinating through shared state is new to you, the pattern generalizes well beyond one vendor's CLI. Our guide to multi-agent AI systems covers the architectures and failure modes that apply to any implementation.

What Is the Difference Between Agent Teams and Claude Code Subagents?

Both parallelize work, and confusing them is the most expensive mistake available here, because the wrong choice can multiply your token bill sevenfold for no benefit. The difference is who talks to whom.

The decision rule is short. If you can describe the work as "go find out X and tell me," use a subagent. If the value depends on two workers disagreeing with each other, use a team.

Sequential work, same-file edits, and heavily dependent tasks are explicitly called out in the agent teams documentation as cases where a single session or subagents are more effective. Coordination overhead is real, and it grows faster than the parallelism gain.

How Do You Enable and Set Up Agent Teams in Claude Code?

Agent teams are off by default. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 to switch them on, either as a shell variable or, more durably, in the env block of your settings.json file.

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

You do not need to restart. Claude Code reapplies settings-file env values to the running session when you save, and rereads the variable each time it spawns an agent.

Before switching it on, it is worth confirming what the default state actually looks like, because the documentation's claim is easy to verify. On a machine where the variable has never been set, neither team directory exists at all:

$ echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
                                  # empty, the flag was never set

$ ls ~/.claude/
commands  debug  ide  plugins  projects  sessions  settings.json  skills

$ ls ~/.claude/teams/
ls: cannot access '/c/Users/<user>/.claude/teams/': No such file or directory

$ ls ~/.claude/tasks/
ls: cannot access '/c/Users/<user>/.claude/tasks/': No such file or directory

That is a useful diagnostic to keep. If you believe teams are enabled but ~/.claude/teams/ is still missing after a session has started, the variable is not reaching Claude Code and no amount of prompt rewording will produce a teammate.

Two constraints catch people out immediately after enabling:

• Interactive sessions only. Spawning teammates requires an interactive session. Under the -p flag, including Agent SDK sessions, Claude does not spawn teammates, and a named subagent runs as an ordinary subagent even with teams enabled.
• Delegation behavior changes globally. While teams are on, any subagent Claude names launches as a teammate. Claude names subagents on its own, so a team can form during work you never framed as team work.

That second point is the single most disruptive side effect of the feature, and the fix is covered in the troubleshooting section below.

How Do You Create and Control Your First Agent Team?

There is no create-team command. You describe the team you want in plain language and Claude spawns it. This prompt shape works because the three roles are independent and none of them waits on another:

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.

Name the teammates in your prompt if you plan to address them later, because the lead assigns names at spawn time and those names are how every message is routed. Telling the lead what to call each teammate is the only way to get names you can predict.

Controlling the Team From the Agent Panel

In the default in-process mode, teammates appear in a panel below your prompt input. The keys are worth memorizing because they are the entire interface:

• Up and down arrows - move the selection between teammates in the panel.
• Enter - open the selected teammate's transcript and type to message it directly.
• Escape - interrupt the selected teammate's current turn without stopping it.
• x - stop the selected teammate entirely.
• Ctrl+T - toggle the shared task list so you can see what is claimed and what is blocked.

While you are viewing a teammate, plain text and skills go to that teammate, but built-in slash commands still run in the lead's session. A teammate's model and fast mode are fixed at spawn, so /model and /fast only ever change the lead. From version 2.1.199 Claude Code shows a notice explaining this instead of silently applying it to the lead.

Assigning Models, Plans, and Tasks

You can specify team size and model in the same sentence that creates the team, and Anthropic's cost guidance recommends Sonnet for teammates as the balance of capability and spend:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

When your prompt names no model, the teammate runs on the lead's current model unless CLAUDE_CODE_SUBAGENT_MODEL is set. Teammates also inherit the lead's effort level, and /effort is the one setting that does apply to a teammate you are viewing.

For risky work, require a plan before any edit. The teammate stays in read-only plan mode, submits a plan to the lead, and revises on rejection until approved. The lead decides autonomously, so give it criteria rather than hoping:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.
Only approve plans that include test coverage.

Tasks are either assigned by the lead or self-claimed by a teammate that has finished its previous task. Claiming uses file locking, so two teammates racing for the same task do not both get it. To end a teammate cleanly, name it: asking the lead to have the researcher teammate shut down sends a shutdown request that the teammate can approve or reject with an explanation.

Which Settings and Commands Control Claude Agent Teams?

Most guides stop at the enable flag. Six further settings change how Claude Agent Teams behave: display mode, teammate model, cache lifetime, task retention, and one option removed in v2.1.234.

The cache setting is the one that costs money without announcing itself. An in-process teammate's requests fall outside the main conversation's cache bucket, so its cache holds for five minutes by default even on a subscription.

On a long-running team that means repeated cache misses, and each miss reprocesses that teammate's full context. Setting subagentPromptCacheTtl to 1h keeps it warm, at the cost of a higher billing rate for one-hour cache writes on the API.

If your organization restricts models through an availableModels allowlist, a blocked model name does not fail the spawn. Claude Code substitutes: a blocked family alias such as opus resolves to the newest permitted version of that family on the Anthropic API and on Claude Platform on AWS, and any other blocked value falls back to the lead's model.

Can You Reuse Teammate Roles Across Projects?

Yes. A widely repeated claim says agent teams have no definition file, no YAML, and no schema, and exist only as prose you paste into the terminal. That reading was fair at launch but is no longer accurate.

The current agent teams documentation states that when spawning a teammate you can reference a subagent type from any subagent scope: project, user, plugin, or CLI-defined. A role defined once is reusable both as a delegated subagent and as a teammate.

Subagent definitions are YAML-frontmatter Markdown files. Project-scope roles live in .claude/agents/ and check into version control, and personal ones live in ~/.claude/agents/. Only name and description are required, per the Claude Code subagents documentation:

---
name: security-reviewer
description: Reviews auth and input handling for security defects.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior security reviewer. Focus on token handling, session
management, and input validation. Report issues with severity ratings.

Save that as .claude/agents/security-reviewer.md and spawn it by name, and the whole team composition becomes a reviewable artifact instead of a prompt someone has to remember:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Two behaviors matter here and neither is obvious. The definition's body is appended to the teammate's system prompt as extra instructions rather than replacing it, and Claude Code adds SendMessage to the definition's tools allowlist so an in-process teammate can still communicate. In a session with the Task tools, it also adds TaskCreate, TaskGet, TaskList, and TaskUpdate.

The gap to plan around: the skills and mcpServers frontmatter fields are not applied when a definition runs as a teammate. Teammates load skills and MCP servers from your project and user settings instead, the same as a regular session. A role that depends on a scoped MCP server will not get one as a teammate.

How Do Hooks and Permissions Keep an Agent Team in Check?

Three hook events fire on team activity: TeammateIdle, TaskCreated, and TaskCompleted. Each uses exit code 2 to reject the action and send feedback, so you enforce rules without reading every transcript.

• TeammateIdle - fires when a teammate is about to go idle. Exit 2 to send feedback and keep it working, which is how you stop a teammate declaring victory early.
• TaskCreated - fires as a task is being created. Exit 2 to prevent creation and explain why, useful for rejecting tasks that are too large to be checked.
• TaskCompleted - fires as a task is marked complete. Exit 2 to block completion, which is where you attach a real verification command.

A TaskCompleted hook wired to your test suite turns "the teammate says it is done" into "the suite agrees it is done." The Claude Code hooks documentation covers the payload each event receives.

Permissions work differently from what most people expect. Teammates start with the lead's permission settings, including --dangerously-skip-permissions if the lead was launched with it. You cannot set per-teammate permission modes at spawn time, only change them afterwards, and every teammate's permission prompt surfaces in the lead session for you to approve.

The security model around inter-agent messages deserves attention if you run teams in auto mode. Claude Code tells a receiving agent that a message came from another Claude session rather than from you, so a teammate cannot approve a permission prompt on your behalf, and a teammate denied an action cannot relay it through another teammate to get around the check.

In auto mode the classifier adds two checks: it treats an approval claim relayed from another agent as untrusted input, and it reviews every message before delivery, including structured protocol messages such as shutdown requests and plan approval responses. A blocked message never reaches its recipient. That is a deliberate boundary against one compromised or confused agent escalating privileges across the team, and it is the same reasoning behind agent handoff testing, where the handoff itself is the thing most likely to fail.

How Do You Verify What an Agent Team Actually Shipped?

You verify it outside the agent, in a real browser. One session producing unverified code is a review problem. Five sessions producing it in parallel is that same problem multiplied by five, arriving at once.

The structural issue is that coding agents operate on a closed surface: they read source code, write source code, and verify with unit tests, type checkers, and linters, all of which also operate on source code. None of them opens a viewport, clicks the button, and confirms the expected page loads. When a teammate reports "passed," it is reporting on the code surface only.

That produces a specific failure class: code that is technically correct while the user-facing result is broken. A button wired to the wrong API, a redirect that 404s, a form that never validates, a modal that will not close. Multiply that by parallel teammates who never saw each other's rendered output and the review burden lands on you.

TestMu AI's Kane CLI is built for exactly this seam. It is a deterministic browser agent for developers, AI coding agents, and CI/CD pipelines that validates rendered UI in a real Chrome browser using natural-language objectives, driving the page through the Chrome DevTools Protocol rather than a synthetic DOM.

The agent writes; Kane CLI proves. Install it and authenticate in two commands:

Agent Mode is what makes it usable from inside a team. Running with --agent --headless suppresses the interactive interface and emits structured NDJSON, one JSON object per line, with a terminal run_end event carrying status, summary, extracted values, token usage, and the Test Manager URL. A teammate can parse that without scraping prose.

npm install -g @testmuai/kane-cli
kane-cli login --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY"

kane-cli run "Sign in and confirm the dashboard loads" --agent --headless

Use basic auth rather than OAuth in agent contexts. OAuth opens a browser consent page, and an agent with no display server cannot click through it. The Kane CLI quick start documentation covers both flows.

You can also teach teammates to reach for verification unprompted. Installing the Kane CLI skill at .claude/skills/kane-cli/SKILL.md makes the agent recognize browser work, build the command, parse the NDJSON, and inspect failure screenshots on its own. Since teammates load project skills at spawn, a project-level skill reaches every teammate automatically.

For framework-level test code rather than browser verification, the open-source TestMu AI agent skills repository carries more than 40 MIT-licensed skills spanning Selenium, Playwright, Cypress, Appium, Jest, pytest, and others across 15+ languages. Install one, or all of them, in a single command:

npx agentskillsforall add https://github.com/LambdaTest/agent-skills.git --skill playwright-skill

A worked example of this loop, where Claude Code writes a feature and Kane CLI verifies it, is in our walkthrough of verifying Claude Code output with Kane CLI.

Note: Five parallel teammates can write more code in an hour than you can review in a day. Kane CLI runs each change in a real Chrome browser and returns an evidence-backed pass or fail your pipeline can gate on. Try TestMu AI free!

What Are the Best Agent Teams Use Cases Across Industries?

The strongest use cases share one shape: work that splits cleanly by domain expertise, where those domains must reconcile before anything ships. Team size stays inside the recommended three-to-five range.

• Fintech and payments - one teammate owns the ledger logic, one owns the payment-provider integration, one owns idempotency and retry behavior. The debate about what happens on a duplicate webhook is the deliverable, and it surfaces before the code hardens.
• Healthcare and regulated SaaS - a data-handling teammate, an audit-logging teammate, and an access-control teammate review the same change against different obligations. Splitting the review means no single pass has to hold every rule at once.
• Ecommerce - cart, pricing, and inventory each get an owner during a checkout rewrite, which is exactly the file-ownership split the documentation recommends to avoid two teammates overwriting each other.
• Media and publishing - a rendering teammate, an accessibility teammate, and a performance teammate work one template in parallel, where the accessibility and performance findings usually contradict each other and need reconciling.
• Enterprise platform teams - multi-repo changes extend the documentation's cross-layer pattern one step further: one teammate per repository, each with a single working directory to track, negotiating the shared API contract between them.
• Developer tooling and QA - competing-hypothesis debugging, where several teammates each pursue a different theory about a flaky failure and actively try to disprove the others rather than confirming the first plausible story.

That last case is the one with the clearest mechanism behind it. Sequential investigation suffers from anchoring: once one theory is explored, everything after it is biased toward that theory. Independent investigators actively trying to refute each other break the anchor, which is why the surviving explanation is more trustworthy.

The same reasoning drives how these systems get tested once they leave your terminal. Our guide to multi agent testing covers verifying what a group of agents collectively did, rather than checking each one in isolation.

When Are Agent Teams Not Worth the Token Cost?

Skip a team when the work is sequential, touches the same files, or only needs an answer rather than a debate. Coordination overhead is close to fixed, so on a short task it is pure loss.

A widely upvoted r/ClaudeCode thread titled "Convince me that agent teams are not pointless" argues that they amount to expensive subagents, on the grounds that idle notifications flood the lead's context and that inter-agent discussion rarely produces value a subagent could not have delivered. The criticism has substance, and it is right for a large share of tasks.

Anthropic's own guidance agrees more than the marketing suggests. The documentation states that agent teams add coordination overhead, use significantly more tokens, and that for sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective. Skip a team when:

• The work is sequential - if task B needs task A's output, teammates queue behind each other and you pay for parallel context windows that are mostly waiting.
• Teammates would edit the same files - two teammates in one file leads to overwrites, and the only real defense is splitting file ownership, which small changes rarely allow.
• Only the answer matters - if you want a result rather than a discussion, a subagent returns it at a fraction of the token cost.
• The task is small - coordination overhead is close to fixed, so on a short task it is pure loss.
• You need it in CI - teams simply do not form in headless or Agent SDK sessions, so this is a constraint rather than a preference.

There is a second cost that does not appear on any bill. Letting a team run unattended increases the risk of wasted effort, so the documentation's advice is to check in, redirect approaches that are not working, and synthesize findings as they arrive. Five teammates running unsupervised for an hour can produce an hour of work in the wrong direction, five times over.

A reasonable default: reach for a team when the value depends on disagreement, and reach for subagents when it does not. If you are choosing between orchestration patterns more broadly, our breakdown of agentic AI orchestration patterns maps the trade-offs beyond a single tool.

Why Are Agent Teams Not Working in Claude Code?

Most reported problems are one of five things, and four are not bugs: the feature is off, an idle row is hidden rather than stopped, Claude chose subagents, a task status lagged, or permission prompts are queuing.

Teammates Are Not Appearing

Check the enable flag first, then check whether the row was hidden rather than stopped. From v2.1.199 an idle teammate's row stays visible while any other agent is still working, and idle rows hide thirty seconds after the whole panel goes idle.

The teammate keeps running and stays addressable while hidden, and messaging it by name brings the row back. When more than three teammates are idle, the surplus rows collapse into a single counter row such as 2 idle agents, which Enter expands.

Claude also decides whether a task warrants a team, so it may have used subagents instead. Subagents and teammates share the same panel, so the panel alone does not confirm a team formed. Ask again and explicitly request an agent team.

Claude Spawns Teammates When You Wanted Subagents

This is the trap that breaks working automation. While teams are enabled, a subagent Claude names launches as a teammate, and the two report back differently: Claude receives a subagent's result on completion, but a teammate only sends an idle notification saying it stopped, without its output.

An orchestration flow waiting on subagent results stalls with no obvious error. Turn teams off to restore the old behavior:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

No new session is needed. One precedence detail matters: setting it to 0 in your user settings.json overrides a shell export, but project settings, local settings, and a --settings payload all apply after user settings, so a value of 1 in any of them wins. Managed settings apply last of all, so if your organization enables teams there, only an administrator can change it.

Tasks Stuck and Agents Stopping Early

Task status can lag: teammates sometimes fail to mark a task complete, which blocks every task depending on it. Check whether the work is genuinely done, then update the status manually or tell the lead to nudge the teammate.

Teammates also stop after errors instead of recovering, so open the transcript, give direct instructions, or spawn a replacement. The lead can stop early too, deciding the team is finished before it is, in which case tell it to keep going.

Too Many Permission Prompts

Every teammate's permission request bubbles up to the lead, so a five-teammate team produces five streams of interruptions in one place. Pre-approve common operations in your permission settings before spawning, rather than approving them one at a time mid-run.

Known Limitations to Plan Around

• No session resumption - /resume and /rewind do not restore in-process teammates, and the lead may try to message teammates that no longer exist. Tell it to spawn new ones.
• One team per session - a session has exactly one team scoped to it. You cannot create additional named teams or share a team across sessions.
• No nested teams - teammates cannot spawn their own teammates. Only the lead manages the team.
• The lead is fixed - the main session leads for its lifetime, and leadership cannot be transferred or promoted to a teammate.
• Shutdown can be slow - teammates finish the current request or tool call before exiting, so a graceful shutdown is not immediate.
• Orphaned tmux sessions - in split-pane mode a tmux session can outlive Claude Code. Run tmux ls and kill the leftover session by name.

What Should You Try First With Agent Teams?

Start with a review, not an implementation. Enable the flag, then ask for three teammates to read your last pull request through a security lens, a performance lens, and a test-coverage lens.

Watch the panel while they work. Read-only tasks with clear boundaries show you the value of parallel exploration without the file-conflict risk of parallel implementation.

Then decide honestly whether the disagreement between those three reviewers was worth roughly seven times the tokens of one session. On research, review, and genuinely independent feature work it usually is. On sequential work it never is, and no prompt fixes that.

Whichever way that lands, the verification gap stays open: parallel agents produce more code than any human can review at the same rate. Install the Kane CLI skill so teammates verify their own work in a real browser, or read how TestMu AI's Agent Testing platform evaluates the agents themselves once they reach production.