tmux × Claude Code 多 Agent 工作流快速上手指南

適用環境：Windows 11 + WSL2 (Ubuntu) + Windows Terminal 目標：在一個 tmux session 裡跑多個 Claude Code，關掉視窗也不會斷

第一部分：安裝

1. 確認 WSL2 已安裝

# PowerShell (管理員)
wsl --install -d Ubuntu
wsl --set-default-version 2

2. WSL 內安裝 tmux

sudo apt update && sudo apt install -y tmux
tmux -V   # 確認版本 (3.3a+)

3. WSL 內安裝 Claude Code

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

第二部分：tmux 核心觀念

┌─────────────────────────────────────────────────┐
│ tmux server（背景常駐，關視窗不會死）              │
│                                                   │
│  ┌─ Session: "work" ──────────────────────────┐  │
│  │                                             │  │
│  │  ┌─ Window 0: "agents" ──────────────────┐ │  │
│  │  │  ┌──────────┬──────────┬──────────┐   │ │  │
│  │  │  │ Pane 0   │ Pane 1   │ Pane 2   │   │ │  │
│  │  │  │ Claude   │ Claude   │ Claude   │   │ │  │
│  │  │  │ Code #1  │ Code #2  │ Code #3  │   │ │  │
│  │  │  └──────────┴──────────┴──────────┘   │ │  │
│  │  └───────────────────────────────────────┘ │  │
│  │                                             │  │
│  │  ┌─ Window 1: "review" ──────────────────┐ │  │
│  │  │  (你的 review / git 操作空間)           │ │  │
│  │  └───────────────────────────────────────┘ │  │
│  └─────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

三層結構：

Session：最外層容器，persist 在背景
Window：像瀏覽器的 tab（可多個）
Pane：Window 內的分割區塊

第三部分：每日只需要記住的指令

開工（每天一次）

# 建立新 session（第一天）
tmux new -s work

# 或接回昨天的 session（之後每天）
tmux attach -t work
# 簡寫
tmux a -t work

tmux 操作（Prefix = Ctrl+b）

所有 tmux 指令都是先按 Ctrl+b 放開，再按對應的鍵。

Pane 操作（最常用）

動作	按鍵	說明
垂直分割	`Ctrl+b` `%`	左右兩欄
水平分割	`Ctrl+b` `"`	上下兩列
切換 Pane	`Ctrl+b` `方向鍵`	移到相鄰 pane
全螢幕切換	`Ctrl+b` `z`	放大/還原當前 pane
關閉 Pane	`Ctrl+d` 或 `exit`	關閉當前 pane
顯示 Pane 編號	`Ctrl+b` `q`	按數字可跳轉

Window 操作

動作	按鍵
新增 Window	`Ctrl+b` `c`
下一個 Window	`Ctrl+b` `n`
上一個 Window	`Ctrl+b` `p`
選擇 Window	`Ctrl+b` `0-9`
重命名 Window	`Ctrl+b` `,`

Session 操作（核心！）

動作	按鍵 / 指令
Detach（脫離但不關閉）	`Ctrl+b` `d`
Attach（重新接回）	`tmux a -t work`
列出所有 session	`tmux ls`
Kill session	`tmux kill-session -t work`

第四部分：三個 Claude Code 的標準開局

手動版（推薦新手先用這個）

# 1. 建立 session
tmux new -s work

# 2. 第一個 pane 已經在了，進入你的專案
cd /mnt/d/Projects/YourProject
claude

# 3. 開第二個 pane（垂直分割）
#    先按 Ctrl+b，再按 %
#    然後在新 pane 裡：
cd /mnt/d/Projects/YourProject
claude

# 4. 開第三個 pane（水平分割）
#    先按 Ctrl+b，再按 "
cd /mnt/d/Projects/YourProject
claude

# 5. 用 Ctrl+b 方向鍵 在三個 pane 之間切換
# 6. 用 Ctrl+b z 放大某個 pane 做 review

一鍵腳本版（熟悉後用這個）

把以下存為 ~/claude-work.sh：

#!/bin/bash
# claude-work.sh - 一鍵啟動多 Claude Code 工作環境
# 用法: ./claude-work.sh [專案路徑] [agent數量]

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

# 如果 session 已存在，直接 attach
if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
    echo "Session '$SESSION_NAME' 已存在，重新接回..."
    tmux attach -t "$SESSION_NAME"
    exit 0
fi

# 建立新 session，第一個 window 叫 "agents"
tmux new-session -d -s "$SESSION_NAME" -n "agents" -c "$PROJECT_DIR"

# 第一個 pane 啟動 Claude Code
tmux send-keys -t "$SESSION_NAME:agents" "claude" Enter

# 根據 agent 數量建立更多 pane
for i in $(seq 2 "$AGENT_COUNT"); do
    if [ $i -le 2 ]; then
        # 第二個 pane：垂直分割
        tmux split-window -h -t "$SESSION_NAME:agents" -c "$PROJECT_DIR"
    else
        # 第三個以上：水平分割最後一個 pane
        tmux split-window -v -t "$SESSION_NAME:agents" -c "$PROJECT_DIR"
    fi
    tmux send-keys -t "$SESSION_NAME:agents" "claude" Enter
done

# 均勻排列所有 pane
tmux select-layout -t "$SESSION_NAME:agents" tiled

# 建立第二個 window 給 review / git 操作
tmux new-window -t "$SESSION_NAME" -n "review" -c "$PROJECT_DIR"

# 建立第三個 window 給雜事（build, test 等）
tmux new-window -t "$SESSION_NAME" -n "misc" -c "$PROJECT_DIR"

# 切回 agents window
tmux select-window -t "$SESSION_NAME:agents"

# Attach
tmux attach -t "$SESSION_NAME"

chmod +x ~/claude-work.sh

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

第五部分：tmux 設定檔（提升體驗）

建立 ~/.tmux.conf：

# ============================================
# tmux 設定 - Claude Code 多 Agent 工作流
# ============================================

# --- 基本設定 ---
set -g default-terminal "tmux-256color"    # 256 色支援
set -as terminal-overrides ",*:Tc"         # 啟用 true color（修正 WSL 顏色灰暗問題）
set -g history-limit 50000                 # 大 scrollback buffer
set -g mouse on                            # 啟用滑鼠（點擊切 pane、拖拉調大小、滾輪翻頁）
set -g base-index 1                        # Window 從 1 開始編號
setw -g pane-base-index 1                  # Pane 從 1 開始編號
set -g renumber-windows on                 # 關掉 window 後自動重新編號
set -sg escape-time 0                      # 無延遲（避免按 Esc 卡頓）

# --- Pane 外觀 ---
set -g pane-border-style "fg=#444444"
set -g pane-active-border-style "fg=#00ff88"   # 當前 pane 綠色邊框

# --- 狀態列 ---
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 標籤
setw -g window-status-format " #I:#W "
setw -g window-status-current-format "#[fg=#1a1a2e,bg=#00ff88,bold] #I:#W "

# --- 方便的快捷鍵 ---

# 用 Ctrl+b r 重新載入設定
bind r source-file ~/.tmux.conf \; display "設定已重新載入"

# 更直覺的分割鍵（| 垂直，- 水平）
bind \\ split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Alt + 方向鍵切 pane（不需要 prefix）
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 切 pane（vim style，不需要 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 一鍵 tiled layout（均勻排列）
bind t select-layout tiled

# Ctrl+b E 一鍵 even-horizontal（並排）
bind e select-layout even-horizontal

設定完後重新載入：

tmux source-file ~/.tmux.conf
# 或在 tmux 內按 Ctrl+b r

第六部分：日常工作流

情境 1：正常開工

打開 Windows Terminal
輸入 wsl
執行 ~/claude-work.sh /mnt/d/Projects/WPF-Refactor 3
三個 Claude Code 同時啟動，開始丟任務

情境 2：需要切去用 VS Code / 瀏覽器

按 Ctrl+b d （detach，tmux 在背景繼續跑）
去用 VS Code、瀏覽器、Visual Studio，愛多久多久
回來時開 Windows Terminal → wsl → tmux a -t claude-work
一切都還在原地，包括所有 Claude Code 的對話狀態

情境 3：Review 某個 agent 的產出

Ctrl+b 方向鍵 切到該 agent 的 pane
Ctrl+b z 放大成全螢幕仔細看
看完按 Ctrl+b z 縮回去
切到 review window（Ctrl+b 2）做 git diff / PR
切回 agents window（Ctrl+b 1）繼續

情境 4：Agent 完成了，丟下一個任務

Ctrl+b 方向鍵 切到完成的 agent
直接在 Claude Code 裡輸入下一個任務（從 task queue）
切回你正在 review 的 pane

情境 5：下班收工

Ctrl+b d （detach）
關掉 Windows Terminal
甚至可以關機（WSL 會被暫停，但 tmux session 會在下次開機後恢復）
   注意：Windows 重開機後需要先進 WSL 再 tmux a

第七部分：搭配 Agent Teams

當你準備用 Claude Code 的 Agent Teams 功能時：

# 1. 先啟動 tmux
tmux new -s team-work

# 2. 在 tmux 裡啟動 Claude Code
cd /mnt/d/Projects/YourProject
claude

# 3. 在 Claude Code 裡啟用 Agent Teams
#    Claude 會自動在 tmux 裡建立 split pane
#    每個 teammate 會拿到自己的 pane + 獨特顏色

# 4. 切換 teammate
#    Shift+Up / Shift+Down（Claude Code 內建）
#    或 Ctrl+b 方向鍵（tmux 原生）

Agent Teams 會自動偵測到你在 tmux 裡，使用 tmux 作為 backend。

第八部分：進階技巧

同時跑多個專案

# 專案 1
tmux new -s wpf-refactor
cd /mnt/d/Projects/WPF-Refactor && claude

# Detach: Ctrl+b d

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

# 切換 session
tmux switch -t wpf-refactor
tmux switch -t twincore

# 或用選單切換
# Ctrl+b s （列出所有 session，方向鍵選擇）

監控所有 pane

# 在 tmux 裡同步輸入到所有 pane（慎用）
# Ctrl+b :
# 輸入: setw synchronize-panes on

# 關閉同步
# Ctrl+b :
# 輸入: setw synchronize-panes off

存取 Windows 檔案的效能提示

# 快：WSL 原生路徑
~/projects/my-app

# 慢：跨 filesystem（但對 Claude Code 的讀寫夠用）
/mnt/d/Projects/WPF-Refactor

# 建議：如果是純 Claude Code 操作，可以 symlink
ln -s /mnt/d/Projects ~/win-projects
cd ~/win-projects/WPF-Refactor

速查卡

╔═══════════════════════════════════════════════╗
║  tmux × Claude Code 速查卡                     ║
╠═══════════════════════════════════════════════╣
║                                                ║
║  啟動    tmux new -s work                      ║
║  接回    tmux a -t work                        ║
║  脫離    Ctrl+b d                              ║
║  列出    tmux ls                               ║
║                                                ║
║  垂直分割  Ctrl+b %  (或 Ctrl+b \)             ║
║  水平分割  Ctrl+b "  (或 Ctrl+b -)             ║
║  切 Pane   Ctrl+b 方向鍵 (或 Alt+方向鍵)      ║
║  放大/縮   Ctrl+b z                            ║
║  關 Pane   Ctrl+d                              ║
║                                                ║
║  新 Window  Ctrl+b c                           ║
║  切 Window  Ctrl+b 1/2/3                       ║
║  均勻排列   Ctrl+b T                           ║
║                                                ║
║  切 Session  Ctrl+b s                          ║
║  重載設定    Ctrl+b r                          ║
║                                                ║
╚═══════════════════════════════════════════════╝

第一部分：安裝​

1. 確認 WSL2 已安裝​

2. WSL 內安裝 tmux​

3. WSL 內安裝 Claude Code​

第二部分：tmux 核心觀念​

第三部分：每日只需要記住的指令​

開工（每天一次）​

tmux 操作（Prefix = Ctrl+b）​

Pane 操作（最常用）​

Window 操作​

Session 操作（核心！）​

第四部分：三個 Claude Code 的標準開局​

手動版（推薦新手先用這個）​

一鍵腳本版（熟悉後用這個）​

第五部分：tmux 設定檔（提升體驗）​

第六部分：日常工作流​

情境 1：正常開工​

情境 2：需要切去用 VS Code / 瀏覽器​

情境 3：Review 某個 agent 的產出​

情境 4：Agent 完成了，丟下一個任務​

情境 5：下班收工​

第七部分：搭配 Agent Teams​

第八部分：進階技巧​

同時跑多個專案​

監控所有 pane​

存取 Windows 檔案的效能提示​

速查卡​

第一部分：安裝

1. 確認 WSL2 已安裝

2. WSL 內安裝 tmux

3. WSL 內安裝 Claude Code

第二部分：tmux 核心觀念

第三部分：每日只需要記住的指令

開工（每天一次）

tmux 操作（Prefix = Ctrl+b）

Pane 操作（最常用）

Window 操作

Session 操作（核心！）

第四部分：三個 Claude Code 的標準開局

手動版（推薦新手先用這個）

一鍵腳本版（熟悉後用這個）

第五部分：tmux 設定檔（提升體驗）

第六部分：日常工作流

情境 1：正常開工

情境 2：需要切去用 VS Code / 瀏覽器

情境 3：Review 某個 agent 的產出

情境 4：Agent 完成了，丟下一個任務

情境 5：下班收工

第七部分：搭配 Agent Teams

第八部分：進階技巧

同時跑多個專案

監控所有 pane

存取 Windows 檔案的效能提示

速查卡