Claude Code’s Agent Teams feature lets you run multiple Claude instances simultaneously on a single task — one acting as a coordinator, others working in parallel on different pieces. For researchers this means things like running a literature-style review from multiple angles at once, or having separate agents tackle independent parts of an analysis. It’s experimental and off by default, but straightforward to enable.
This is different from Claude’s standard subagents, where each worker runs independently, can’t communicate with the others, and can’t be redirected once launched. With agent teams, the team lead actively monitors progress, can course-correct agents that go off track, and teammates can message each other directly — sharing findings, flagging conflicts, or adjusting their approach based on what others discover.
Note: Split-pane mode (sections 1–3) gives each agent its own visible terminal pane and requires tmux. If you’d rather skip that setup, jump to section 4 for the simpler no-tmux option — it works in any terminal and is a good place to start.
This guide is written for Windows users running Claude Code through WSL (Windows Subsystem for Linux). If you’re on a Mac or running Linux natively, you can skip sections 2 and 3 entirely — tmux is either already available in a recent enough version via your package manager, or straightforward to install, and there’s no Windows Terminal limitation to work around. Section 1 (enabling the feature flag) and section 4 (in-process mode) apply to everyone regardless of operating system.
1. Enable the feature
The quickest way is a single launch command. Run this from inside a tmux session (more on that in section 3):
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode tmux
Or set both options permanently in ~/.claude/settings.json so you don’t have to type them each time:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
"teammateMode": "tmux"
}
These are two separate flags: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enables the feature at all, and teammateMode controls how agents are displayed. You need both.
2. Getting the right version of tmux
For split-pane mode, Claude uses tmux — a terminal multiplexer that lets one terminal window host multiple independent sessions at once. Claude requires tmux 3.2a or higher.
The WSL problem: If you’re on Ubuntu 20.04 (the default for many WSL installations), the package manager only offers tmux 3.0a — too old. The usual workaround, snap install tmux, won’t help either: Snap requires a background service called systemd (which manages system processes on Linux), and systemd is disabled by default in most WSL
environments. The fix is to build tmux directly from its source code. The command below handles everything — installing dependencies, downloading the latest release, compiling, and cleaning up — and only needs to be run once. Copy and paste the entire command into the WSL terminal:
sudo apt update && \ sudo apt install -y build-essential libevent-dev ncurses-dev bison pkg-config && \ TEMP_DIR=$(mktemp -d) && cd $TEMP_DIR && \ curl -s https://api.github.com/repos/tmux/tmux/releases/latest \ | grep "browser_download_url" | grep ".tar.gz" \ | sed 's/.*"\(https[^\"]*\)".*/\1/' | xargs wget && \ tar -xzf tmux-*.tar.gz && cd tmux-*/ && \ ./configure && make && sudo make install && \ cd ~ && rm -rf $TEMP_DIR && tmux -V
Or if you have the GitHub CLI (gh) installed (which I highly suggest to make it easier for agents to communicate with GitHub):
gh release download --repo tmux/tmux --pattern '*.tar.gz'
The new tmux installs to /usr/local/bin/tmux, which takes priority over the old system version automatically. If you’re currently inside a tmux session, run tmux kill-server and restart for the new version to take effect. The last line of the install command (tmux -V) prints the version so you can confirm it worked.
| Method | Version | Works? |
|---|---|---|
| Ubuntu 20.04 apt | 3.0a | ❌ |
| Ubuntu 22.04+ apt | 3.2a | ✅ minimum |
| Build from source | 3.6a (latest, as of March 2026) | ✅ |
3. The WSL workflow
Windows Terminal — the default terminal app for WSL on Windows — doesn’t support Claude’s split-pane mode on its own. For split panes to work, you need to launch Claude from inside a tmux session. The workflow is:
# 1. Open WSL in Windows Terminal as usual # 2. Start a tmux session (you can name it anything) tmux new -s work # 3. Launch Claude from inside that tmux session CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode tmux
From here, ask Claude to spawn a team and describe the task. Each agent automatically gets its own pane. Use Shift+Down to cycle through agents and type to send a message to whichever one is active.
4. Skip tmux: in-process mode
If sections 2 and 3 look like more setup than you want right now, start here. In-process mode runs all agents inside your existing terminal — no tmux required, works in Windows Terminal, and takes no extra configuration. You lose the side-by-side visual layout, but the multi-agent coordination works identically. This is the easier way to try the feature for the first
time.
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode in-process
Use Shift+Down to cycle through agents and send them messages directly.
