Agent teams (experimental)

In the lesson on choosing a pattern, the agent team came last: you need it when the workers have to talk to each other. It is an experimental feature, off by default.

How a team works

An agent team is several Claude Code sessions working together. Your session is the lead: it spawns teammates, each in its own context. Teammates message each other directly, and you can message any of them too. Subagents, by contrast, mostly just return a result.

A teammate loads your CLAUDE.md, MCP servers and skills, plus the task from the lead — but not the lead’s conversation. So everything the task needs has to be in the task.

Turn it on for one session

Do not turn teams on globally. Make a separate file, for example .claude/team.json:

{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
  "teammateMode": "in-process",
  "hooks": {
    "TeammateIdle": [
      { "hooks": [ { "type": "command", "command": "jq -r '.teammate_name' >> \"$CLAUDE_PROJECT_DIR/.claude/teammates.log\"" } ] }
    ]
  }
}

• env turns teams on only for sessions started with this file;
• teammateMode: "in-process" keeps teammates right in your terminal — it works in any terminal;
• the TeammateIdle hook fires when a teammate is about to go idle and logs its name. That is your proof the team formed: in the bottom panel, subagents and teammates look the same.

Starting the lead:

CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude --settings .claude/team.json

CLAUDE_CODE_ENABLE_TODO_TOOLS=1 gives the session task tools on any model. Without it, those tools exist only on some older models, and on the rest teammates coordinate by messages alone, with no shared task list. Ctrl+T shows and hides the list itself.

Teammates from your definitions

Name a subagent definition in the task, and the teammate gets its tools, instructions and model, unless the task specifies a different model. Read-only reviewers with the line tools: Read, Grep, Glob are a good choice: they read and search, but do not edit files or run commands.

Create an agent team to review the change saved in .claude/review.diff. Spawn two teammates:
one named security, using the security-reviewer agent type, and one named tests, using the
test-reviewer agent type. When both have reported, write one combined report.

Claude Code spawns teammates without asking. When the work is done, stop them by name:

Ask the security and tests teammates to shut down.

Each one either agrees and exits, or declines and explains why. A teammate whose row disappeared from the panel is hidden, not stopped — name it too.

Competing hypotheses

The strongest use is debugging when the cause of a bug is unknown. Make a read-only hypothesis-tester definition and ask the lead to spawn three teammates: each owns one hypothesis and messages the others to challenge theirs. The lead records the explanation that survived the debate and the hypotheses that fell away.