smux

smux

Tmux 窗格控制與跨窗格代理通訊。所有跨窗格互動請使用 tmux-bridge（高階 CLI）。僅在需要低階控制時才回退到原始 tmux 指令。

tmux-bridge — 跨窗格通訊

一個 CLI，讓任何 AI 代理能與任何其他 tmux 窗格互動。透過純 bash 運作。每個指令都是原子性的：type 輸入文字（不含 Enter），keys 發送特殊按鍵，read 擷取窗格內容。

不要等待或輪詢

其他窗格中的代理會透過 tmux-bridge 回覆您。它們的回覆會直接以 [tmux-bridge from:...] 訊息出現在您的窗格中。不要 sleep、輪詢、讀取目標窗格等待回應，或迴圈。輸入您的訊息，按下 Enter，然後繼續。

唯一需要讀取目標窗格的時機是：

• 在與其互動之前（由讀取守衛強制執行）
• 在輸入之後，確認文字已送達，然後再按 Enter
• 當與非代理窗格（純 shell、執行中的程序）互動時

讀取守衛

CLI 強制執行「先讀後動」。除非您已先讀取窗格，否則無法對其執行 type 或 keys。

1. tmux-bridge read <target> 將窗格標記為「已讀」
2. tmux-bridge type/keys <target> 檢查該標記 — 若未讀取則報錯
3. 成功執行 type/keys 後，標記會被清除 — 下次互動前必須再次讀取

$ tmux-bridge type codex "hello"
error: must read the pane before interacting. Run: tmux-bridge read codex

指令參考

指令	說明	範例
tmux-bridge list	顯示所有窗格，包含目標、pid、指令、大小、標籤	tmux-bridge list
tmux-bridge type <target> <text>	輸入文字，不按 Enter	tmux-bridge type codex "hello"
tmux-bridge message <target> <text>	輸入文字，自動附加寄件者資訊與回覆目標	tmux-bridge message codex "review src/auth.ts"
tmux-bridge read <target> [lines]	讀取最後 N 行（預設 50）	tmux-bridge read codex 100
tmux-bridge keys <target> <key>...	發送特殊按鍵	tmux-bridge keys codex Enter
tmux-bridge name <target> <label>	為窗格命名（顯示於 tmux 邊框）	tmux-bridge name %3 codex
tmux-bridge resolve <label>	印出標籤對應的窗格目標	tmux-bridge resolve codex
tmux-bridge id	印出此窗格的 ID	tmux-bridge id

目標解析

目標可以是：

• tmux 原生格式：session:window.pane（例如 shared:0.1）、窗格 ID（%3）或視窗索引（0）
• 標籤：透過 tmux-bridge name 設定的任意字串 — 會自動解析

讀取-動作-讀取循環

每次互動都遵循讀取 → 動作 → 讀取。CLI 會強制執行此流程。

向代理發送訊息：

tmux-bridge read codex 20                    # 1. 讀取 — 滿足讀取守衛
tmux-bridge message codex 'Please review src/auth.ts'
                                              # 2. 訊息 — 自動附加寄件者資訊，不按 Enter
tmux-bridge read codex 20                    # 3. 讀取 — 確認文字已送達
tmux-bridge keys codex Enter                 # 4. 按鍵 — 提交
# 停止。不要讀取 codex 等待回覆。代理會回覆到您的窗格。

批准提示（非代理窗格）：

tmux-bridge read worker 10                   # 1. 讀取 — 查看提示
tmux-bridge type worker "y"                  # 2. 輸入
tmux-bridge read worker 10                   # 3. 讀取 — 確認
tmux-bridge keys worker Enter                # 4. 按鍵 — 提交
tmux-bridge read worker 20                   # 5. 讀取 — 查看結果

訊息慣例

message 指令會自動附加寄件者資訊與位置：

[tmux-bridge from:claude pane:%4 at:3:0.0] Please review src/auth.ts

接收者會看到：誰發送的（from）、回覆的目標窗格（pane）以及工作階段/視窗位置（at）。當您看到此標頭時，請使用 tmux-bridge 回覆至標頭中的窗格 ID。

代理對代理工作流程

# 1. 為自己命名
tmux-bridge name "$(tmux-bridge id)" claude

# 2. 探索其他窗格
tmux-bridge list

# 3. 發送訊息（讀取-動作-讀取）
tmux-bridge read codex 20
tmux-bridge message codex 'Please review the changes in src/auth.ts'
tmux-bridge read codex 20
tmux-bridge keys codex Enter

對話範例

代理 A (claude) 發送：

tmux-bridge read codex 20
tmux-bridge message codex 'What is the test coverage for src/auth.ts?'
tmux-bridge read codex 20
tmux-bridge keys codex Enter

代理 B (codex) 在其提示中看到：

[tmux-bridge from:claude pane:%4 at:3:0.0] What is the test coverage for src/auth.ts?

代理 B 使用標頭中的窗格 ID 回覆：

tmux-bridge read %4 20
tmux-bridge message %4 '87% line coverage. Missing the OAuth refresh token path (lines 142-168).'
tmux-bridge read %4 20
tmux-bridge keys %4 Enter

---

原始 tmux 指令

當您需要 tmux-bridge 無法提供的直接 tmux 控制時使用這些指令 — 工作階段管理、視窗導覽、建立窗格或低階腳本。

擷取輸出

tmux capture-pane -t shared -p | tail -20    # 最後 20 行
tmux capture-pane -t shared -p -S -          # 整個回滾緩衝區
tmux capture-pane -t shared:0.0 -p           # 特定窗格

發送按鍵

tmux send-keys -t shared -l -- "text here"   # 輸入文字（文字模式）
tmux send-keys -t shared Enter               # 按 Enter
tmux send-keys -t shared Escape              # 按 Escape
tmux send-keys -t shared C-c                 # Ctrl+C
tmux send-keys -t shared C-d                 # Ctrl+D (EOF)

對於互動式 TUI，將文字和 Enter 分開發送：

tmux send-keys -t shared -l -- "Please apply the patch"
sleep 0.1
tmux send-keys -t shared Enter

窗格與視窗

# 建立窗格（優先於新視窗）
tmux split-window -h -t SESSION              # 水平分割
tmux split-window -v -t SESSION              # 垂直分割
tmux select-layout -t SESSION tiled          # 重新平衡

# 導覽
tmux select-window -t shared:0
tmux select-pane -t shared:0.1
tmux list-windows -t shared

工作階段管理

tmux list-sessions
tmux new-session -d -s newsession
tmux kill-session -t sessionname
tmux rename-session -t old new

Claude Code 模式

# 檢查工作階段是否需要輸入
tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"

# 批准提示
tmux send-keys -t worker-3 'y' Enter

# 檢查所有工作階段
for s in shared worker-2 worker-3 worker-4; do
  echo "=== $s ==="
  tmux capture-pane -t $s -p 2>/dev/null | tail -5
done

提示

• 讀取守衛會強制執行 — 每次 type/keys 前都必須讀取
• 每個動作都會清除讀取標記 — type 後，在 keys 前再次讀取
• 永遠不要等待或輪詢 — 代理窗格會透過 tmux-bridge 回覆到您的窗格
• 及早為窗格命名 — 比使用 %N ID 更容易
• type 使用文字模式 — 特殊字元會原樣輸入
• read 預設為 50 行 — 傳入更大的數字以取得更多上下文
• 非代理窗格是例外 — 您確實需要讀取它們以查看輸出
• 使用 capture-pane -p 輸出到 stdout（對腳本至關重要）
• 目標格式：session:window.pane（例如 shared:0.0）