Claude Code Agent Teams: Setup, Limits, and Hosted Alternatives

Short answer: Claude Code agent teams let one lead session coordinate several independent Claude Code sessions through a shared task list and direct teammate messaging. Enable the experimental feature, begin with three teammates, divide work by files or investigative angle, and make the lead wait for every result before integration. Use a single session or subagents when the work is sequential. Use an always-on hosted runtime when the job must survive beyond a developer terminal, run on a schedule, or operate through chat and external tools.

Agent teams are not simply “more Claude.” Each teammate has a separate context window and consumes tokens independently. That separation is valuable when three people could genuinely work at once. It is expensive and awkward when everyone needs the same file, the same approval, or the output of the previous step.

This guide covers the current Claude Code implementation, including the behavior documented for version 2.1.178 and later. The feature remains experimental, so verify details against the installed version before turning a useful prototype into a team standard.

Contents

• What an agent team actually creates
• Enable the feature
• Run a first team safely
• Split work without file conflicts
• Control permissions and costs
• Understand the current limits
• Choose subagents, worktrees, or hosting

What Claude Code agent teams actually create

An agent team has four moving parts: the lead, its teammates, a shared task list, and a mailbox. The lead is the Claude Code session you started. It creates work, assigns or exposes tasks, receives messages, and combines the final result. Each teammate is another full Claude Code session with its own context window.

That last detail matters. A teammate loads project instructions such as CLAUDE.md, configured skills, and MCP servers. It receives the lead's spawn prompt, but it does not inherit the lead's conversation history. If the authentication design or the failing test was discussed twenty minutes earlier, put those facts in the teammate brief or a project file.

If two workers need to debate, share discoveries, or claim tasks from one queue, use a team. If the lead only needs a compact answer back, use a subagent.

Step 1: enable the experimental feature

Agent teams are disabled by default. Add the documented environment setting to your user or project settings:

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

Restart Claude Code after changing settings. Then ask explicitly for an agent team. Claude may choose ordinary subagents if it judges the task too small, and both worker types can appear in the same agent panel. If direct teammate communication is part of your test, say so in the prompt.

The default display mode is in-process. Teammates appear below the prompt and can be selected from the keyboard. Split panes require tmux or iTerm2 tooling; the default works in an ordinary terminal and is the least surprising place to begin.

Step 2: run a first team on a review task

Review is a forgiving first experiment because teammates can inspect the same change through different lenses without editing it. Give each one a named responsibility and require a common report shape.

Spawn an agent team with three teammates to review PR #142.
Name them security, performance, and tests.

Security: inspect authentication, authorization, and input handling.
Performance: look for extra queries, blocking calls, and hot-path allocations.
Tests: check changed behavior, missing edge cases, and flaky assumptions.

Each teammate must return file paths, evidence, severity, and a proposed fix.
Have them challenge duplicate or conflicting findings. Do not edit the branch.
Wait for all three before producing one deduplicated report.

This prompt does more than name roles. It defines the artifact, removes write access from the assignment, and tells the lead not to rush ahead. Those details prevent the common outcome where one teammate writes a vague paragraph while the lead starts fixing the first issue it sees.

Know what success looks like

Before trusting the result, check three things. First, each teammate appears as a teammate rather than a subagent. Second, the shared task list shows separate owners and clear completion state. Third, the final report cites evidence from all three streams instead of repeating the lead's first impression.

Run the experiment on a small pull request. Record elapsed time, token usage, useful findings, duplicated findings, and interventions. A team that finds two extra defects but costs six times as much may still be worthwhile for security-sensitive code. The same economics are poor for a routine formatting change.

Step 3: split implementation by ownership, not job title

Parallel implementation works when the boundaries are visible in the repository. “Backend agent” and “frontend agent” sound clean, but both may need the shared types file. A safer split names files, interfaces, and a handoff order.

Build the audit-log export feature with three teammates.

api owns server/export/* and writes the JSON schema first.
ui owns web/export/* and may only consume the committed schema.
tests owns test/export/* and fixtures; it must not change production files.

No teammate may edit files owned by another teammate.
API must message the schema path and example payload to UI and tests.
Require tests to report the exact commands and results.
Wait for every teammate, inspect the combined diff, then run the full suite.

The shared task list supports dependencies. Use them. The UI task can remain blocked until the schema task is complete. A blocked task is cheaper than two incompatible implementations that need to be reconciled later.

Use a worktree when isolation matters

Claude Code agent teammates share the project environment. They are coordinated sessions, not automatically isolated branches. For risky implementation or likely file overlap, separate Git worktrees are easier to reason about. The trade-off is manual integration and less direct coordination.

A practical pattern is to use agent teams for read-only investigation and design, then create worktrees for independently reviewed implementation branches. Do not add more agents to compensate for a repository that lacks stable module boundaries.

Step 4: set permissions and cost boundaries before spawning

Teammates begin with the lead's permission settings. If the lead starts with unrestricted permission skipping, teammates inherit that posture. Individual modes can be changed later, but per-teammate permission modes cannot currently be set at spawn time.

For a first run, keep the lead in an approval-aware mode and make the assignment read-only. Permission prompts from teammates surface in the lead session. Another teammate cannot approve a prompt or relay consent on your behalf, which prevents a denied action from being laundered through the team mailbox.

Reusable subagent definitions can give a teammate a tool allowlist and model. They are useful for roles such as security-reviewer or test-runner. Be precise about what carries over: team coordination tools remain available, while skills and mcpServers fields from that subagent definition are not applied to the teammate.

Budget in teammates, not prompts

Token use rises with each active teammate because every one has a separate context. Anthropic recommends starting with roughly three to five teammates for work that truly benefits from parallelism. In practice, three is plenty for a first pilot.

• Use cheaper models for mechanical review when quality remains acceptable.
• Keep spawn briefs self-contained so teammates do not repeatedly rediscover context.
• Give each teammate several related tasks rather than spawning one session per tiny check.
• Use /usage and your organization billing controls to compare team runs with a single-session baseline.
• Stop idle or unproductive teammates instead of leaving them available “just in case.”

Current limitations you should design around

The experimental label is meaningful. In-process teammates do not return when you use /resume or /rewind. Task status can lag behind completed work. Shutdown waits for the current request or tool call. A session has one team, the lead cannot be replaced, and teammates cannot create nested teams.

There is also a softer limit: the team lives inside an interactive coding session. It is excellent for a focused engineering effort. It is not, by itself, a durable worker that wakes tomorrow, reads a Telegram request, uses a browser, and reports after the laptop is closed.

When to choose subagents, worktrees, or a hosted runtime

Choose Claude Code subagents

Use subagents for bounded exploration, log analysis, test review, or any task where only the result matters. They preserve the parent context and usually consume fewer coordination tokens. They are also easier to constrain with reusable role definitions.

Choose manual sessions with Git worktrees

Use worktrees when implementation isolation matters more than inter-agent conversation. Each session can own a branch and a filesystem tree. You get explicit diffs and merges at the cost of handling coordination yourself.

Choose an always-on hosted agent runtime

Use a hosted runtime when work must continue outside the terminal session: scheduled checks, browser operations, incoming chat requests, persistent files and memory, scoped secrets, or multi-day follow-up. GolemWorkers gives an AI agent a dedicated environment with terminal, browser, files, messaging, and schedules. Claude Code can still be one coding tool inside that broader worker.

The two layers solve different problems. Claude Code agent teams organize several coding sessions around one engineering task. A hosted runtime keeps the worker reachable and operational between tasks. For unattended production work, keep external actions behind explicit approval and verify every deployment separately.

Failure modes worth testing

The lead starts coding instead of coordinating

Tell it to wait for teammates and reserve integration for the end. If the lead duplicates a worker's task, the division was not explicit enough.

Two teammates overwrite the same file

Stop the run, inspect Git history and the working tree, and recover the intended changes deliberately. Retry with file ownership or separate worktrees. Do not ask another teammate to “merge whatever is there.”

A task stays blocked after the work is done

Check the teammate transcript and the actual artifact. If the deliverable exists, ask the lead to update the task or nudge the teammate. Do not treat a green task list as stronger evidence than tests and files.

Permission prompts become the bottleneck

Pre-approve the narrow, repeatable operations the team needs. Keep destructive or external actions gated. If every worker needs a different policy, a single shared team may be the wrong boundary.

A resumed lead talks to teammates that no longer exist

Spawn replacements with a compact handoff from committed files and task artifacts. In-process teammate resumption is not currently supported.

Verification checklist

• The experimental flag is enabled in the intended settings scope.
• The panel shows teammates, not only subagents.
• Every teammate has a named, non-overlapping responsibility.
• The spawn prompt includes task-specific context missing from conversation history.
• Tasks name artifacts, owners, dependencies, and a definition of done.
• Write access is restricted or divided by file ownership.
• The lead waits for all required findings before integration.
• The combined diff and full test suite are checked after parallel work.
• Token usage is compared with a single-session baseline.
• Important conclusions are saved outside transient teammate context.

Bottom line

Claude Code agent teams are useful when independent thinking or separate module ownership can shorten real engineering work. Start with review, use three teammates, define the evidence they must return, and measure the result. Avoid teams for sequential chores or shared-file editing.

If the coding effort needs a durable outer loop, add one intentionally. A dedicated GolemWorkers agent can receive work from chat, retain project files, run scheduled checks, and call Claude Code inside an isolated worker environment. Create a hosted AI agent, or compare the runtime boundary in OpenClaw vs Claude Code.

Primary sources

• Anthropic: Orchestrate teams of Claude Code sessions — enablement, architecture, task coordination, permissions, limits, and troubleshooting.
• Anthropic: Create custom subagents — subagent lifecycle, scopes, tools, and model configuration.
• Anthropic: Manage Claude Code costs — usage tracking, organizational controls, and token-cost guidance.
• Anthropic: Run parallel Claude Code sessions with Git worktrees — filesystem and branch isolation for parallel implementation.
• Anthropic: Claude Code permissions — approval modes and tool-specific controls.