DEV Community

Cover image for claude code agent teams: what they are, how to enable them, and how to run one
Lookbk
Lookbk

Posted on

claude code agent teams: what they are, how to enable them, and how to run one

You asked Claude Code to "spawn three teammates", and either nothing happened or you got subagents instead. Both are common, and both have a plain explanation in the official docs. Claude Code agent teams are several Claude Code sessions that work together: one session is the team lead, the others are teammates, and they share a task list and message each other directly. The feature is experimental and off by default, so you have to switch it on before any of this works.

This post follows the official agent teams page and restates it in our own words: what a team is, how to turn it on, how to see your teammates, and what to check when it misbehaves.

What a Claude Code agent team is

One session acts as the team lead. It coordinates the work, hands out tasks and pulls the results together. Teammates are separate Claude Code instances, each with its own context window, and they can talk to each other without going through the lead. You can also message any teammate yourself.

A team has four parts:

Part Role
Team lead The main session that spawns teammates and coordinates
Teammates Separate instances working on assigned tasks
Task list Shared work items that teammates claim and finish
Mailbox The messaging system between agents

Tasks are pending, in progress or completed. A task can depend on other tasks, and it shows as blocked until those finish. Teammates do not claim a blocked task on their own, although you or the lead can still assign it. When a teammate finishes a task that others depend on, Claude Code unblocks the dependents automatically. Claiming uses file locking so two teammates cannot grab the same task at once.

Agent teams or subagents

The docs suggest checking for a lighter option first. Subagents work inside a single session and report back to the main agent. Teammates share a task list, claim work and talk to each other.

Subagents Agent teams
Context Own window; results return to the caller Own window; fully independent
Communication Report back to the caller Teammates message each other
Coordination The main agent manages the work Messages plus a shared task list
Best for Focused tasks where only the result matters Work that needs discussion and collaboration
Token use Lower Higher, since each teammate is a separate instance

Teams add coordination overhead and use noticeably more tokens. They pay off when teammates can work independently: research and review, new modules or features, debugging with competing hypotheses, and changes that cross frontend, backend and tests. For sequential tasks, edits to the same file or work with many dependencies, a single session or subagents fit better.

How to enable agent teams

Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, either in your shell or in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
Enter fullscreen mode Exit fullscreen mode

Two side effects are worth knowing. First, once teams are enabled, a subagent that Claude gives a name launches as a teammate. Claude names subagents on its own so it can message them later, so a team can form without you asking for one, and Claude Code does not ask you to confirm the launch. Second, spawning teammates needs an interactive session. In non-interactive mode with the -p flag, including Agent SDK sessions, no teammates are spawned and a named subagent runs as an ordinary subagent.

Start your first team

Describe the task and the roles in plain language. The docs use a design review as the model example, because the three roles are independent:

I'm designing a CLI tool that helps developers track comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.
Enter fullscreen mode Exit fullscreen mode

Claude fills the shared task list, spawns a teammate for each angle, lets them explore and then synthesizes what they found. You can also state a count and a model, for example four teammates on one named model. Claude Code picks a teammate's model from the first source that applies: the model your prompt names, then the model in a subagent definition, then CLAUDE_CODE_SUBAGENT_MODEL when it is set to something other than inherit, then the lead's current model.

Claude sometimes picks subagents even when you wanted a team. Subagents show up in the same agent panel as teammates, so the panel alone does not prove a team exists. If that happens, ask again and say explicitly that you want an agent team.

Watch and steer your teammates

Teammates are listed in the agent panel below the prompt input. Use the up and down arrows to select one, press Enter to open its transcript and message it, and press Escape to clear the selection. While you are viewing a transcript, Escape interrupts that teammate's current turn. Press x on a selected teammate to stop it, and Ctrl+T toggles the task list.

Idle rows stay visible while any agent is still working. Once everyone is idle they hide after 30 seconds and return on the teammate's next turn; the teammate keeps running meanwhile. When more than three are idle, the extra rows collapse into one row such as 2 idle agents, and Enter expands it.

To end a teammate cleanly, ask the lead by name, for example "Ask the researcher teammate to shut down". The teammate can approve or reject with an explanation.

Choose a display mode

There are two modes:

  • In-process: every teammate runs inside your main terminal. It works in any terminal with no extra setup.
  • Split panes: each teammate gets its own pane, so you see everyone's output at once. It needs tmux, or iTerm2 with the it2 CLI and its Python API enabled.

Teammates run in-process until you change the teammateMode setting. To use split panes, set it to "auto" in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}
Enter fullscreen mode Exit fullscreen mode

With "auto", teammates open in panes when Claude Code runs inside tmux or iTerm2 and run in-process elsewhere. If you run outside both and have tmux installed, set "tmux"; the panes open in a separate tmux session. If panes do not open in your iTerm2 window, set "iterm2". The docs add that tmux has known limitations on some operating systems and works best on macOS.

Where the files live

Teams and tasks are stored locally under a name made of session- and the first eight characters of the session ID.

  • Each agent's mailbox is a JSON file at ~/.claude/teams/ followed by the team name, then inboxes/, then the agent name with a .json ending.
  • The team config sits at config.json in the same team folder. Claude Code removes it when the session ends. It holds runtime state, so do not edit it by hand; your changes are overwritten.
  • The task list lives under ~/.claude/tasks/ in a folder with the team name. It stays on disk after the session; cleanupPeriodDays controls how long it is kept.

A file such as .claude/teams/teams.json in your project is not recognized as configuration. To define reusable roles, use subagent definitions and name one when you ask for a teammate, for example a security-reviewer type. Claude Code applies the definition's tools and model, and appends its body to the teammate's instructions in process mode. It does not apply the definition's skills field; teammates load skills from your project and user settings.

Permissions and context

A new teammate starts with the lead's permission mode, and you cannot set per-teammate modes at spawn time. Permission prompts from teammates appear in the lead session, so you approve them there. A message from another agent is never treated as your consent.

Each teammate loads the same project context as a normal session: CLAUDE.md, MCP servers and skills. It does not inherit the lead's conversation history, so put task details in the spawn prompt.

Practical advice from the docs

  • Start with three to five teammates. Three focused ones often beat five scattered ones.
  • Aim for roughly five or six tasks per teammate, each a self-contained unit such as a function, a test file or a review.
  • Give each teammate its own files. Two teammates editing one file leads to overwrites.
  • If the lead starts doing the work itself, tell it to wait for its teammates to finish.
  • Begin with research or review, such as a PR review with one teammate each on security, performance and test coverage.
  • Check in on the team. Leaving it unattended for long raises the risk of wasted effort.
  • Hooks can enforce quality gates: TeammateIdle, TaskCreated and TaskCompleted each accept exit code 2 to send feedback.

When teammates do not appear

First, remember that Claude decides whether a task is big enough for a team, so a trivial request may not spawn anyone. Second, in in-process mode, look in the agent panel and check for hidden idle rows; messaging the teammate by name brings the row back. Third, for split panes, confirm tmux is installed and on your PATH, or that it2 is installed and the Python API is on.

If Claude keeps spawning teammates when you wanted subagents, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0 in your user settings.json. Claude Code rereads it at the next spawn, so no restart is needed. Project settings, local settings or a --settings payload that set it to 1 still win over the user file.

Something to try in Claude Code

If you want a visual project to try in Claude Code, take a look at the free Signal Glitch skill: a website hero that tunes in like a receiver. Your own photograph and headline are one broadcast frame, and they arrive through two real signal chains that each have to lock: the frame rolls with its blanking bar until vertical hold catches, the lines shear and flag until horizontal sync settles, colour stays off until the colour burst locks and then slides into register, while a stream joined without a key frame smears its macroblocks until a rolling refresh sweeps them clean, and then the frame holds sharp and readable for about 70% of a 12 second loop, with the pointer acting as interference that the stream repairs and the copy on panels keyed over the picture like a receiver's own display. It comes from our open-source repository at https://github.com/lookbkdev/lookbk-skills, and this guide shows how to install it.

This post was drafted with AI assistance and checked against the skill's SKILL.md.

Top comments (0)