Setting up Claude Code agent teams, multiple sessions working together

You may already know subagents. You give the main agent a task, it spawns a focused worker, that worker works in its own context and reports a result back at the end. Works well for bounded jobs. Agent teams are something different. Here several full Claude Code sessions run at the same time, each with its own context window, and they talk to each other directly instead of only reporting to the boss. One session is the team lead, coordinates, distributes tasks and summarises at the end. The others are teammates and can contradict each other, test hypotheses, exchange findings. The feature is experimental and off by default. This playbook shows how I switch it on and when it is worth the considerably higher token consumption.

1. Understand when a team beats a subagent

The most important step happens before the setup, namely deciding whether you need a team at all. Rule of thumb from the docs: agent teams shine when parallel exploration brings real value. Four scenarios where they pay off: research and review where several teammates investigate different aspects simultaneously and then challenge each other. New modules where each builds their own piece without stepping on the others. Debugging with competing hypotheses, each testing a different theory. And cross-layer work that touches frontend, backend and tests at the same time.

What you do NOT take a team for: sequential tasks, edits to the same file, work with many dependencies. There a single session or a subagent is more effective and cheaper. Teams cost coordination overhead and considerably more tokens, every teammate is its own Claude instance with its own context.

2. Activate the feature

Agent teams are disabled by default. You switch them on via the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, either directly in your shell or in settings.json:

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

I take the settings.json route, then it is stable project-wide and I do not forget it at the next terminal. If you only want to try it out, set the variable as a shell export and restart Claude Code. Since it is experimental, behaviour can change between versions, so do not be surprised if an update shifts something.

3. Start the first team

After activating it, you give Claude the task in normal language and describe the team structure. No special command, just a prompt. An example from the docs that works well because the three roles are independent:

I am designing a CLI tool that tracks TODO comments in a codebase.
Create an agent team that looks at this from different angles,
one on UX, one on technical architecture, one as devil's advocate.

Claude then builds a team with a shared task list, spawns a teammate for each perspective, has them explore the problem, summarises the findings and cleans the team up at the end. Important: Claude never creates a team unprompted. Either you ask for it, or Claude proposes it and you confirm.

4. Control the display, in-process or split panes

There are two display modes. In-process means all teammates run in your main terminal, you page through them with Shift+Down and type directly to send one a message. Works in any terminal without extra setup. Split panes give every teammate its own pane, you see all outputs at once and click into a pane to interact directly. But that needs tmux or iTerm2.

The default is auto, which takes split panes if you are already sitting in a tmux session, otherwise in-process. If you want a fixed mode, set teammateMode in ~/.claude/settings.json:

{
  "teammateMode": "in-process"
}

For a single session the flag claude --teammate-mode in-process also works. For split panes you need tmux or iTerm2 with the it2 CLI installed, and with iTerm2 you additionally have to enable the Python API under Settings, General, Magic. I mostly run in-process, that saves me the tmux faff and is plenty for three or four teammates.

5. Set the number and model of the teammates

Claude decides for itself how many teammates it spawns, based on the task. But you can specify it exactly:

Create a team with 4 teammates that refactor these modules in parallel.
Use Sonnet for every teammate.

A detail that often gets overlooked: teammates do NOT inherit the lead's /model choice by default. If you want them all to follow the lead model, set the option "Default teammate model" under /config to Default, meaning the leader's model. Otherwise teammates may run on a different model than you thought, and with four parallel Opus teammates you notice that on the bill at the latest.

6. Enforce plan approval for risky tasks

For delicate changes you can require a teammate to plan before touching anything. It then works in read-only plan mode until the lead signs off on its approach:

Spawn an architect teammate that refactors the auth module.
Require plan approval before it makes any change.

When the teammate has finished planning, it sends a plan approval request to the lead. The lead reviews and approves, or rejects with feedback. On rejection the teammate stays in plan mode, reworks and submits again. The lead decides autonomously, you influence it through criteria in the prompt, such as "only approve plans with test coverage" or "reject anything that touches the DB schema". If you do not have plan mode under control yet, work through the plan mode playbook first, the principle is the same, only applied to a teammate here.

7. Talk to individual teammates directly

Every teammate is a complete, independent Claude Code session. You can write to each directly to give extra instructions, ask questions or change course. In in-process mode you page through the teammates with Shift+Down and then type the message. Enter shows a teammate's session, escape interrupts its current turn, Ctrl+T toggles the task list. After the last teammate, Shift+Down jumps back to the lead. In split pane mode you simply click into the respective pane.

That is the real difference from subagents. With a subagent you cannot intervene during the work, it runs through and reports back. With a teammate you can call into the running session mid-flight.

8. Distribute tasks and let the team communicate

The shared task list coordinates the work. Tasks have three states: pending, in progress, completed. They can depend on each other, a pending task with open dependencies can only be claimed once its predecessors are done. The lead can assign tasks explicitly ("give task X to teammate Y"), or teammates self-claim, after finishing a teammate grabs the next free, unblocked task by itself. So that two do not grab the same task at once, the system uses file locking.

Communication runs through a mailbox. Messages are delivered automatically, the lead does not have to poll. When a teammate is done and stops, it reports that to the lead automatically. Among themselves teammates address each other by the name the lead assigns at spawn time. Tip: tell the lead in the prompt what to name the teammates, then you can address them specifically in later prompts instead of guessing.

9. Enforce quality gates with team hooks

Agent teams bring their own hook events, with which you enforce rules when teammates finish work or tasks are created. TeammateIdle fires shortly before a teammate goes idle, with exit code 2 you send feedback and keep it working. TaskCreated fires when a task is created, exit code 2 prevents creation and gives feedback. TaskCompleted fires on completion, exit code 2 blocks the completion.

In practice that means you can, for example, prevent a teammate going idle while the tests are red, or a task being marked done without a lint check having run. If you have not set up hooks yet, the best start is the hooks debugging playbook, the exit-code-2 pattern is explained there already and applies the same way here.

10. Clean up and reuse roles

Two things at the end. First cleaning up: when you are done, tell the lead to do a cleanup. That removes the shared team resources. Careful, the cleanup fails while active teammates are still running, so shut the individual teammates down first ("please shut down the researcher teammate"). Team config lives under ~/.claude/teams/{team-name}/config.json, the task list under ~/.claude/tasks/{team-name}/. Do not edit the config by hand, Claude overwrites it on the next state update.

Second, reusable roles. When spawning you can reference an existing subagent definition ("spawn a teammate with the security-reviewer agent type"). The teammate then inherits its tools allowlist and model, and the definition is appended to its system prompt as an extra instruction. That way you define a role once and use it both as a delegated subagent and as a team teammate. The coordination tools such as SendMessage and the task management always stay available to the teammate, even if the definition restricts other tools.

What next

If you are now unsure whether a specific task needs a team, a subagent or just a skill, read Subagent or skill or MCP tool, that gives you the decision matrix. And if you want to go deeper into classic subagent orchestration, so workers that report back instead of talking to each other, Structuring a subagent team is the next step. Content-wise this all belongs in level 5, so look at the lesson Research, critic, analyst alongside, the adversarial pattern from step 1 is described there as a concept.

Source

All specifics in this playbook come from the official Claude Code documentation, as of 8 June 2026: https://code.claude.com/docs/en/agent-teams