Setting Up Claude Code Agent Teams With Wsl2 and Tmux on Windows

Claude Code’s agent teams feature lets you spin up multiple Claude instances that work in parallel, each in its own visible terminal pane. On Windows, visualizing this properly requires WSL2 and tmux — here’s how to set it up from scratch.

Prerequisites

• Windows 10/11 with WSL2 available
• A Claude Code subscription (Pro or Max) with Opus 4.6 access
• Your repos somewhere accessible (e.g. C:\dev\github\reponame)

Step 1 — Enable WSL2 and Install Ubuntu

Open an elevated PowerShell and run:

1

wsl --install

Reboot when prompted. Ubuntu will finish its setup on first launch — create your Linux username and password when asked.

If you already have WSL1, upgrade to WSL2:

1

wsl --set-default-version 2

Step 2 — Install Dependencies Inside WSL

Open your Ubuntu terminal:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Update packages
sudo apt update && sudo apt upgrade -y

# Install tmux and build tools
sudo apt install -y tmux git curl build-essential

# Install Node.js via nvm (required by Claude Code)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts

Step 3 — Install Claude Code

1
2

npm install -g @anthropic-ai/claude-code
claude --version   # verify it installed correctly

Step 4 — Configure tmux

Create ~/.tmux.conf with settings optimized for agent teams:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

cat > ~/.tmux.conf << 'EOF'
# Mouse support — click panes, resize, scroll
set -g mouse on

# Large scrollback for agent logs
set -g history-limit 50000

# Colors
set -g default-terminal "tmux-256color"

# Auto-close pane when process exits
set -g remain-on-exit off

# Split panes and stay in current directory
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Vim-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Refresh status bar every 5 seconds
set -g status-interval 5
EOF

Note: Don’t try to tmux source-file ~/.tmux.conf at this point — that command only works inside a running tmux session. The config will be picked up automatically when you start tmux in Step 6.

Step 5 — Symlink Your Windows .claude Config to WSL

Claude Code stores agents, skills, teams, and settings in ~/.claude. Rather than maintaining two separate configs, symlink WSL’s ~/.claude to your Windows one so both environments share the same setup.

1
2
3
4
5
6
7
8

# Remove the default WSL ~/.claude folder (safe — it's just empty runtime data)
rm -rf ~/.claude

# Symlink to the Windows .claude folder
ln -s /mnt/c/Users/YourWindowsUsername/.claude ~/.claude

# Verify they match — you should see agents, skills, teams, etc.
ls ~/.claude

Replace YourWindowsUsername with your actual Windows username (e.g. Steve).

Step 6 — Enable Agent Teams in Claude Code

Agent teams are experimental and disabled by default. Enable them by editing ~/.claude/settings.json:

1
2

# Open settings.json — since it's symlinked this also updates your Windows config
cat ~/.claude/settings.json

Add the env block if it isn’t there already:

1
2
3
4
5

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

Step 7 — Launch Claude Inside tmux

Start a named tmux session pointed at your project. You can either cd first or pass the path directly:

1
2
3
4
5
6

# Option A — cd first
cd /mnt/c/dev/github/reponame
tmux new-session -s claude -c .

# Option B — full path directly
tmux new-session -s claude -c /mnt/c/dev/github/reponame

Performance tip: WSL accessing files through /mnt/c/ is slower than native Linux paths for file-heavy operations. For intensive agent team tasks you may eventually want to clone repos directly into the WSL filesystem (e.g. ~/dev/reponame). For getting started it’s fine either way.

Once inside the tmux session, start Claude Code:

1

claude

Claude Code detects that it’s running inside tmux and will automatically use split-pane mode when agent teams are spawned — no extra configuration needed.

Step 8 — Try It Out

Give Claude a task that warrants a team: