Agent teams in Claude Code

Claude Code has an experimental feature called Agent teams that lets you orchestrate several Claude Code instances at once: one team lead that coordinates work, plus independent teammates that each run in their own context window and can talk directly to each other. This post is a quick tour of what it is, why I think it actually matters for day-to-day engineering, how to set it up on Linux, Windows and macOS, and a concrete two-teammate setup you can copy.

Team lead

Main Claude Code session

coordinates work, assigns tasks

Teammate

doc-keeper

updates docs in lockstep

mailbox

Teammate

research-scout

scans the web, proposes

Shared state

Task list

teammates self-claim work

Each teammate is a full Claude Code session with its own context window. The lead spawns them, the task list keeps work in one place, and the mailbox lets teammates message each other directly - no need to round-trip through the lead.

What it is

Unlike subagents, which run inside a single session and only report results back to the main agent, teammates in an agent team are full Claude Code sessions with:

• their own context window and conversation history,
• a shared task list everyone can see and claim from,
• a mailbox so teammates can message each other directly,
• and a UI (in-process or split panes) where you can step into any teammate’s session and interact with it.

A single lead orchestrates the team, but every teammate is a real, independent Claude that you can read, redirect, or interrupt at any time.

Why it actually matters on the job

The thing I like is observability. When you give a single agent a large task, you get a summary back. With a team, each teammate runs in its own pane (or pageable session) and you can watch what each one is doing as it happens: which file it is reading, which hypothesis it is testing, which doc it is rewriting. You can interrupt a teammate that has gone off the rails without killing the whole session. You can also message a single teammate (“focus only on the auth flow, ignore the rest”) without polluting the lead’s context.

A few other things that show up quickly in practice:

• Parallel exploration beats sequential. Two teammates testing two competing hypotheses for a flaky test usually converge faster than one agent doing both serially, because they do not anchor on the first plausible explanation they find.
• Specialised roles stay specialised. A reviewer that only does security, or a writer that only updates docs, drifts less than a generalist trying to do everything in one context.
• You stay in the loop. The shared task list is a real artifact you can read, not a hidden plan inside one agent’s head.

Token cost is the trade-off: each teammate has its own context window and burns tokens independently. For research, review, refactors and new modules it is usually worth it. For routine fixes it is overkill.

Enable the feature

Agent teams need Claude Code v2.1.32 or newer. Check with:

claude --version

Then enable the feature by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, either in your shell environment or in ~/.claude/settings.json:

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

That is the minimum. Once it is on, ask Claude in natural language to create a team and it will spawn teammates, set up the shared task list, and coordinate work.

Platform setup

Agent teams support two display modes:

• In-process: every teammate runs inside your main terminal. You cycle through them with Shift+Down and type to message the currently focused one. Works in any terminal, no extra setup.
• Split panes: each teammate gets its own pane. This is the mode you want when you actually need to see everyone working at once. Requires tmux or iTerm2.

The default is "auto", which picks split panes when you are already inside a tmux session and in-process otherwise. You can force the mode with the teammateMode key in ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

Or per-session:

claude --teammate-mode in-process

Linux

Install tmux through the system package manager:

# Debian / Ubuntu
sudo apt install tmux

# Fedora
sudo dnf install tmux

# Arch
sudo pacman -S tmux

Then start a tmux session and launch Claude inside it. With teammateMode set to "auto" or "tmux", split panes activate automatically.

Windows

Native Windows Terminal is not supported for split-pane mode. The practical path is WSL2 with a real Linux distro inside, then install tmux there exactly like the Linux instructions above and run claude inside the WSL shell. In-process mode also works fine from any Windows terminal if you do not need the split-pane view.

macOS

Install tmux via Homebrew:

brew install tmux

For the best experience use iTerm2 with its native tmux integration. iTerm2 ships a control mode (-CC) that turns tmux’s internal panes into real iTerm2 windows and tabs, with native scroll, mouse and clipboard:

# Start a new control-mode session
tmux -CC

# Or attach to an existing one
tmux -CC attach

iTerm2 also supports a richer integration through the it2 CLI plus the Python API. Install the CLI (see github.com/mkusaka/it2) and enable the API in iTerm2 → Settings → General → Magic → Enable Python API. With that in place, agent teams in split-pane mode will use iTerm2 windows directly.

tmux mouse mode (Linux, Windows / WSL, macOS)

By default tmux does not handle mouse events, so you cannot click between teammate panes, scroll their history, or select text with the mouse. Turn it on by adding one line to ~/.tmux.conf:

set -g mouse on

Reload the config in a running session with tmux source ~/.tmux.conf, or just restart your tmux session. With mouse on you can click a pane to focus it, scroll wheel inside a pane scrolls the buffer, and dragging selects text. On macOS in tmux -CC mode you can skip this entirely - iTerm2 handles mouse natively.

A concrete two-teammate setup

Here is the setup I am running while writing code: my lead session does the work, and two background teammates ride along with me.

• doc-keeper keeps documentation in lockstep with the code as I change it.
• research-scout continuously looks for online discussion about similar code and proposes optimisations.

Both are defined as project-scoped subagents under .claude/agents/. Agent teams accept any subagent definition, so the same role can be reused for ad-hoc delegations or as a teammate in a team.

.claude/agents/doc-keeper.md

---
name: doc-keeper
description: Keeps repository documentation in lockstep with source changes.
tools: Read, Edit, Glob, Grep
model: sonnet
---

You are the documentation steward for this repository.

Your job:
1. When the lead tells you a file has changed (or after a TaskCompleted event
   touching source files), reread the affected source and the matching docs.
2. Update READMEs, inline JSDoc/typedoc/godoc, and any architectural notes
   so they describe the new behaviour. Remove statements that became false.
3. Keep examples in docs compilable - run a quick mental check that imports
   and signatures still match the code.
4. If a change deserves a new doc page, propose it back to the lead instead
   of silently creating one.

Style rules:
- Match the existing voice and structure of the docs you edit.
- No marketing tone, no "powerful" / "seamless" filler.
- Mention exact file paths and symbol names so docs stay greppable.

Never edit source code. If the source needs a change before the docs make
sense, say so to the lead and stop.

.claude/agents/research-scout.md

---
name: research-scout
description: Watches the web for discussions of similar code and proposes improvements.
tools: WebSearch, WebFetch, Read, Grep
model: sonnet
---

You are an independent research scout running alongside the main coding
session. Your job is to find external knowledge the lead probably does not
have time to dig up.

Loop:
1. Periodically scan recent files the lead has touched. Pick the top concept,
   library, algorithm or pattern that you do not already have notes on.
2. Search the web (blog posts, GitHub issues, mailing lists, conference
   talks) for current discussion of that topic. Bias toward sources from
   the last 18 months.
3. Read the most relevant 2-3 results in full.
4. Send the lead one short message with: the pattern in our code, what the
   community is doing differently, and a concrete proposal (one or two
   sentences max). Cite URLs.

Hard rules:
- Never edit code or docs. You only research and recommend.
- Do not propose changes you cannot back with a specific external source.
- Skip generic advice. If you cannot find a useful, specific finding, stay
  quiet on that file and move on.

Spin up the team

With both definitions in place and the experimental flag enabled, ask the lead in natural language to spawn the team. For example:

Set up an agent team to work alongside me on this codebase:
- Spawn a teammate using the doc-keeper agent type, name it docs.
- Spawn a teammate using the research-scout agent type, name it scout.

Workflow:
- After every non-trivial edit I make, send docs a message with the file
  path and a one-line summary of what changed.
- Have scout pick the most interesting file I have touched in the last
  ten minutes and look for relevant discussion online. Scout messages me
  directly with concrete proposals, citing URLs.

Wait for them to finish their current turn before checking in.

The lead reads the two agent definitions, spawns the teammates with those names, and from then on you can:

• press Shift+Down (in-process) to cycle between lead, docs and scout and read what they are doing,
• click into a pane (split mode) to message a teammate directly,
• press Ctrl+T to toggle the shared task list and see what is in flight.

When you are done, ask the lead to clean up - never the teammates:

Clean up the team.

Known rough edges

This is still experimental. The ones you will hit fastest:

• /resume and /rewind do not restore in-process teammates. After a resume, tell the lead to spawn fresh ones.
• Teammates occasionally forget to mark a task complete and block dependent tasks. If something looks stuck, check the task list and nudge.
• Split panes do not work in VS Code’s integrated terminal, the default Windows Terminal, or Ghostty. Use iTerm2 on macOS, tmux on Linux/WSL, or fall back to in-process.
• One team per lead. Clean up before creating a new one.

What I’d reach for next

• Hooks for quality gates: TeammateIdle, TaskCreated and TaskCompleted let you keep a teammate working until a check passes (exit code 2 = “go back and try again”).
• Subagents for one-shot delegations where you do not need cross-talk.
• Git worktrees when you want to run multiple Claude sessions yourself, without automated coordination.

Source: official documentation at code.claude.com/docs/en/agent-teams.