---
title: tmux × Claude Code multi-agent workflow
title_en: tmux × Claude Code multi-agent workflow
description: Run multiple Claude Code agents in a single tmux session on WSL2 Ubuntu — survive window closes, with install steps, core concepts, and day-to-day commands.
sidebar_label: tmux × Claude Code workflow
---

# tmux × Claude Code multi-agent workflow

> Environment: Windows 11 + WSL2 (Ubuntu) + Windows Terminal
> Goal: run multiple Claude Code instances inside a single tmux session that survives closing the terminal window.

---

## Part 1: install

### 1. Confirm WSL2 is installed

```powershell
# PowerShell (Administrator)
wsl --install -d Ubuntu
wsl --set-default-version 2
```

### 2. Install tmux inside WSL

```bash
sudo apt update && sudo apt install -y tmux
tmux -V   # Verify version (3.3a+)
```

### 3. Install Claude Code inside WSL

```bash
curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor
```

---

## Part 2: tmux core concepts

```
┌─────────────────────────────────────────────────┐
│ tmux server (runs in the background, survives   │
│              terminal closes)                    │
│                                                   │
│  ┌─ Session: "work" ──────────────────────────┐  │
│  │                                             │  │
│  │  ┌─ Window 0: "agents" ──────────────────┐ │  │
│  │  │  ┌──────────┬──────────┬──────────┐   │ │  │
│  │  │  │ Pane 0   │ Pane 1   │ Pane 2   │   │ │  │
│  │  │  │ Claude   │ Claude   │ Claude   │   │ │  │
│  │  │  │ Code #1  │ Code #2  │ Code #3  │   │ │  │
│  │  │  └──────────┴──────────┴──────────┘   │ │  │
│  │  └───────────────────────────────────────┘ │  │
│  │                                             │  │
│  │  ┌─ Window 1: "review" ──────────────────┐ │  │
│  │  │  (your review / git workspace)         │ │  │
│  │  └───────────────────────────────────────┘ │  │
│  └─────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
```

**Three layers:**

- **Session**: the outermost container; persists in the background
- **Window**: like browser tabs (you can have many)
- **Pane**: a split region inside a window

---

## Part 3: the only commands you need daily

### Starting the day (once)

```bash
# Create a new session (first time)
tmux new -s work

# Or reattach to yesterday's session (every day after)
tmux attach -t work
# Shorthand
tmux a -t work
```

### tmux key bindings (Prefix = Ctrl+b)

Every tmux command is: press `Ctrl+b`, release, then press the next key.

#### Pane operations (most common)

| Action               | Keys              | Notes                          |
| -------------------- | ----------------- | ------------------------------ |
| Vertical split       | `Ctrl+b` `%`      | Two columns                    |
| Horizontal split     | `Ctrl+b` `"`      | Two rows                       |
| Switch pane          | `Ctrl+b` `arrow`  | Move to adjacent pane          |
| Zoom toggle          | `Ctrl+b` `z`      | Maximize/restore current pane  |
| Close pane           | `Ctrl+d` or `exit`| Close current pane             |
| Show pane numbers    | `Ctrl+b` `q`      | Press digit to jump            |

#### Window operations

| Action            | Keys           |
| ----------------- | -------------- |
| New window        | `Ctrl+b` `c`   |
| Next window       | `Ctrl+b` `n`   |
| Previous window   | `Ctrl+b` `p`   |
| Select window     | `Ctrl+b` `0-9` |
| Rename window     | `Ctrl+b` `,`   |

#### Session operations (the important part!)

| Action                              | Keys / command              |
| ----------------------------------- | --------------------------- |
| **Detach (leave but don't kill)**   | `Ctrl+b` `d`                |
| **Attach (come back)**              | `tmux a -t work`            |
| List all sessions                   | `tmux ls`                   |
| Kill session                        | `tmux kill-session -t work` |

---

## Part 4: standard three-Claude-Code opener

### Manual version (recommended for first-timers)

```bash
# 1. Create the session
tmux new -s work

# 2. The first pane is already there — cd into your project
cd /mnt/d/Projects/YourProject
claude

# 3. Open a second pane (vertical split)
#    Press Ctrl+b, then %
#    Then in the new pane:
cd /mnt/d/Projects/YourProject
claude

# 4. Open a third pane (horizontal split)
#    Press Ctrl+b, then "
cd /mnt/d/Projects/YourProject
claude

# 5. Use Ctrl+b + arrow keys to move between the three panes
# 6. Use Ctrl+b z to zoom a pane when reviewing
```

### One-shot script version (once you're comfortable)

Save as `~/claude-work.sh`:

```bash
#!/bin/bash
# claude-work.sh - one-shot launcher for a multi-Claude-Code workspace
# Usage: ./claude-work.sh [project-path] [agent-count]

PROJECT_DIR="${1:-/mnt/d/Projects/YourProject}"
AGENT_COUNT="${2:-3}"
SESSION_NAME="claude-work"

# If the session already exists, just attach
if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
    echo "Session '$SESSION_NAME' already exists, reattaching..."
    tmux attach -t "$SESSION_NAME"
    exit 0
fi

# Create a new session with first window named "agents"
tmux new-session -d -s "$SESSION_NAME" -n "agents" -c "$PROJECT_DIR"

# Launch Claude Code in the first pane
tmux send-keys -t "$SESSION_NAME:agents" "claude" Enter

# Create more panes based on agent count
for i in $(seq 2 "$AGENT_COUNT"); do
    if [ $i -le 2 ]; then
        # Second pane: vertical split
        tmux split-window -h -t "$SESSION_NAME:agents" -c "$PROJECT_DIR"
    else
        # Third and beyond: horizontal split on the last pane
        tmux split-window -v -t "$SESSION_NAME:agents" -c "$PROJECT_DIR"
    fi
    tmux send-keys -t "$SESSION_NAME:agents" "claude" Enter
done

# Tile all panes evenly
tmux select-layout -t "$SESSION_NAME:agents" tiled

# Second window for review / git work
tmux new-window -t "$SESSION_NAME" -n "review" -c "$PROJECT_DIR"

# Third window for misc (build, test, etc.)
tmux new-window -t "$SESSION_NAME" -n "misc" -c "$PROJECT_DIR"

# Switch back to the agents window
tmux select-window -t "$SESSION_NAME:agents"

# Attach
tmux attach -t "$SESSION_NAME"
```

```bash
chmod +x ~/claude-work.sh

# Usage
~/claude-work.sh /mnt/d/Projects/WPF-Refactor 3
~/claude-work.sh /mnt/d/Projects/TwinCore 2
```

---

## Part 5: tmux config (quality-of-life)

Create `~/.tmux.conf`:

```bash
# ============================================
# tmux config - Claude Code multi-agent workflow
# ============================================

# --- Basics ---
set -g default-terminal "tmux-256color"    # 256-color support
set -as terminal-overrides ",*:Tc"         # Enable true color (fixes washed-out colors on WSL)
set -g history-limit 50000                 # Large scrollback buffer
set -g mouse on                            # Mouse on (click to switch pane, drag to resize, scroll wheel)
set -g base-index 1                        # Windows numbered from 1
setw -g pane-base-index 1                  # Panes numbered from 1
set -g renumber-windows on                 # Auto-renumber after closing a window
set -sg escape-time 0                      # Zero delay (fixes Esc-key lag)

# --- Pane appearance ---
set -g pane-border-style "fg=#444444"
set -g pane-active-border-style "fg=#00ff88"   # Green border on the active pane

# --- Status bar ---
set -g status-style "bg=#1a1a2e,fg=#e0e0e0"
set -g status-left "#[fg=#00ff88,bold] [#S] "
set -g status-left-length 20
set -g status-right "#[fg=#888888] %Y-%m-%d %H:%M "
set -g status-interval 5

# Window labels
setw -g window-status-format " #I:#W "
setw -g window-status-current-format "#[fg=#1a1a2e,bg=#00ff88,bold] #I:#W "

# --- Handy key bindings ---

# Ctrl+b r reloads the config
bind r source-file ~/.tmux.conf \; display "Config reloaded"

# More intuitive split keys (| vertical, - horizontal)
bind \\ split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Alt + arrow keys to switch panes (no prefix needed)
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Alt + h/j/k/l to switch panes (vim style, no prefix)
bind -n M-h select-pane -L
bind -n M-l select-pane -R
bind -n M-k select-pane -U
bind -n M-j select-pane -D

# Ctrl+b T for tiled layout (even grid)
bind t select-layout tiled

# Ctrl+b E for even-horizontal (side by side)
bind e select-layout even-horizontal
```

Reload after editing:

```bash
tmux source-file ~/.tmux.conf
# Or press Ctrl+b r inside tmux
```

---

## Part 6: daily workflows

### Scenario 1: normal start of day

```
1. Open Windows Terminal
2. Type wsl
3. Run ~/claude-work.sh /mnt/d/Projects/WPF-Refactor 3
4. Three Claude Codes start up — hand out tasks
```

### Scenario 2: need to switch to VS Code / browser

```
1. Press Ctrl+b d (detach — tmux keeps running in the background)
2. Use VS Code, browser, Visual Studio, whatever, for as long as you want
3. Come back: open Windows Terminal → wsl → tmux a -t claude-work
4. Everything is exactly where you left it, including all Claude Code conversation state
```

### Scenario 3: reviewing an agent's output

```
1. Ctrl+b + arrow to switch to that agent's pane
2. Ctrl+b z to zoom it full-screen for a closer look
3. Ctrl+b z again to unzoom
4. Switch to the review window (Ctrl+b 2) for git diff / PR
5. Switch back to the agents window (Ctrl+b 1) and continue
```

### Scenario 4: agent done, hand it the next task

```
1. Ctrl+b + arrow to the finished agent
2. Type the next task into Claude Code (from your task queue)
3. Switch back to whichever pane you were reviewing
```

### Scenario 5: end of day

```
1. Ctrl+b d (detach)
2. Close Windows Terminal
3. You can even shut down (WSL gets paused, but the tmux session resumes after reboot)
   Note: after a Windows reboot, you'll need to start WSL first, then tmux a
```

---

## Part 7: pairing with Agent Teams

When you're ready to use Claude Code's Agent Teams feature:

```bash
# 1. Start tmux first
tmux new -s team-work

# 2. Launch Claude Code inside tmux
cd /mnt/d/Projects/YourProject
claude

# 3. Enable Agent Teams inside Claude Code
#    Claude will automatically create split panes in tmux
#    Each teammate gets its own pane + distinct color

# 4. Switching teammates
#    Shift+Up / Shift+Down (built into Claude Code)
#    Or Ctrl+b + arrow (native tmux)
```

Agent Teams auto-detects that you're in tmux and uses tmux as its backend.

---

## Part 8: advanced tips

### Multiple projects at once

```bash
# Project 1
tmux new -s wpf-refactor
cd /mnt/d/Projects/WPF-Refactor && claude

# Detach: Ctrl+b d

# Project 2
tmux new -s twincore
cd /mnt/d/Projects/TwinCore && claude

# Switch sessions
tmux switch -t wpf-refactor
tmux switch -t twincore

# Or use the picker
# Ctrl+b s (lists all sessions, navigate with arrows)
```

### Broadcasting to all panes

```bash
# Sync input to all panes inside tmux (use sparingly)
# Ctrl+b :
# Type: setw synchronize-panes on

# Turn off sync
# Ctrl+b :
# Type: setw synchronize-panes off
```

### Performance tip for Windows files

```bash
# Fast: native WSL path
~/projects/my-app

# Slow: cross-filesystem (but fast enough for Claude Code's read/write)
/mnt/d/Projects/WPF-Refactor

# Suggested: for pure Claude Code work, just symlink it
ln -s /mnt/d/Projects ~/win-projects
cd ~/win-projects/WPF-Refactor
```

---

## Cheat sheet

```
╔═══════════════════════════════════════════════╗
║  tmux × Claude Code cheat sheet                ║
╠═══════════════════════════════════════════════╣
║                                                ║
║  Start     tmux new -s work                    ║
║  Reattach  tmux a -t work                      ║
║  Detach    Ctrl+b d                            ║
║  List      tmux ls                             ║
║                                                ║
║  V-split    Ctrl+b %  (or Ctrl+b \)            ║
║  H-split    Ctrl+b "  (or Ctrl+b -)            ║
║  Switch pane Ctrl+b arrow (or Alt+arrow)      ║
║  Zoom       Ctrl+b z                           ║
║  Close pane Ctrl+d                             ║
║                                                ║
║  New window     Ctrl+b c                       ║
║  Switch window  Ctrl+b 1/2/3                   ║
║  Tile layout    Ctrl+b T                       ║
║                                                ║
║  Switch session Ctrl+b s                       ║
║  Reload config  Ctrl+b r                       ║
║                                                ║
╚═══════════════════════════════════════════════╝
```