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 (Administrator)
wsl --install -d Ubuntu
wsl --set-default-version 2

2. Install tmux inside WSL

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

3. Install Claude Code inside WSL

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)

# 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)

# 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:

#!/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"

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:

# ============================================
# 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:

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

Part 6: daily workflows

Scenario 1: normal start of day

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

Scenario 2: need to switch to VS Code / browser

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

Scenario 3: reviewing an agent's output

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

Scenario 4: agent done, hand it the next task

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

Scenario 5: end of day

Ctrl+b d (detach)
Close Windows Terminal
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:

# 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

# 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

# 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

# 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                       ║
║                                                ║
╚═══════════════════════════════════════════════╝

Part 1: install​

1. Confirm WSL2 is installed​

2. Install tmux inside WSL​

3. Install Claude Code inside WSL​

Part 2: tmux core concepts​

Part 3: the only commands you need daily​

Starting the day (once)​

tmux key bindings (Prefix = Ctrl+b)​

Pane operations (most common)​

Window operations​

Session operations (the important part!)​

Part 4: standard three-Claude-Code opener​

Manual version (recommended for first-timers)​

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

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

Part 6: daily workflows​

Scenario 1: normal start of day​

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

Scenario 3: reviewing an agent's output​

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

Scenario 5: end of day​

Part 7: pairing with Agent Teams​

Part 8: advanced tips​

Multiple projects at once​

Broadcasting to all panes​

Performance tip for Windows files​

Cheat sheet​