# Agent teams (experimental)

Course: Claude Code: Pro Level — https://zero2vibecode.com/learn/claude-code-pro
Canonical URL: https://zero2vibecode.com/learn/claude-code-pro/4-4-agent-teams
Verified against: Claude Code v2.1.292 (2026-10-15)
Last updated: 2026-10-15

An agent team is several Claude Code sessions where your session is the lead and the teammates message each other directly. The feature is experimental and off by default. Turn it on only for specific sessions, build teammates from read-only definitions, and stop them by name.

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`:

```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:

```bash
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.

```text
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**:

```text
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.

**Careful.** 
While teams are on, a subagent Claude names starts as a teammate — a team can form even though you asked for subagents. Teammates inherit your permission mode, except dontAsk, and with --dangerously-skip-permissions every one of them runs that way. Teammates do not start in claude -p, and /resume and /rewind do not bring back in-process teammates. Every active teammate spends tokens until it exits: keep the team small, put model: sonnet in the definitions, and stop everyone as soon as they have reported.

**Practice in the terminal.** Use grep to check that test-reviewer only reads, copy it to hypothesis-tester.md, and write .claude/team.json with env, teammateMode and a TeammateIdle hook. In a real project you would then rewrite the copy's name, description and instructions for testing a hypothesis.