Back to Details

smux

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

smux

smux

Tmux pane control and cross-pane agent communication. Use 
tmux-bridge
(the high-level CLI) for all cross-pane interactions. Fall back to raw tmux commands only when you need low-level control.
Tmux面板控制与跨面板Agent通信。所有跨面板交互请使用
tmux-bridge
（高级CLI工具）。仅当需要底层控制时，才使用原生tmux命令。

tmux-bridge — Cross-Pane Communication

tmux-bridge — 跨面板通信

A CLI that lets any AI agent interact with any other tmux pane. Works via plain bash. Every command is atomic: 
type
types text (no Enter), 
keys
sends special keys, 
read
captures pane content.
一款允许任意AI Agent与其他tmux面板交互的CLI工具，通过纯bash实现。每个命令都是原子性的：
type
用于输入文本（不按回车），
keys
用于发送特殊按键，
read
用于捕获面板内容。

DO NOT WAIT OR POLL

请勿等待或轮询

Other panes have agents that will reply to you via tmux-bridge. Their reply appears directly in YOUR pane as a 
[tmux-bridge from:...]
message. Do not sleep, poll, read the target pane for a response, or loop. Type your message, press Enter, and move on.
The ONLY time you read a target pane is:
  • Before interacting with it (enforced by the read guard)
  • After typing to verify your text landed before pressing Enter
  • When interacting with a non-agent pane (plain shell, running process)
其他面板中的Agent会通过tmux-bridge向您回复，回复内容会直接显示在您的面板中，格式为
[tmux-bridge from:...]
消息。请勿休眠、轮询、读取目标面板以获取回复或循环等待。输入消息后按回车，然后继续其他操作即可。
仅在以下情况需要读取目标面板：
  • 交互前（由读取防护机制强制要求）
  • 输入后（按回车前验证文本是否输入成功）
  • 与非Agent面板交互时（纯Shell、运行中的进程）

Read Guard

读取防护机制

The CLI enforces read-before-act. You cannot 
type
or 
keys
to a pane unless you have read it first.
  1. tmux-bridge read <target>
    marks the pane as "read"
  2. tmux-bridge type/keys <target>
    checks for that mark — errors if you haven't read
  3. After a successful 
    type
    /
    keys
    , the mark is cleared — you must read again before the next interaction
$ tmux-bridge type codex "hello"
error: must read the pane before interacting. Run: tmux-bridge read codex
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

Command Reference

命令参考

CommandDescriptionExample
tmux-bridge list
Show all panes with target, pid, command, size, label
tmux-bridge list
tmux-bridge type <target> <text>
Type text without pressing Enter
tmux-bridge type codex "hello"
tmux-bridge message <target> <text>
Type text with auto sender info and reply target
tmux-bridge message codex "review src/auth.ts"
tmux-bridge read <target> [lines]
Read last N lines (default 50)
tmux-bridge read codex 100
tmux-bridge keys <target> <key>...
Send special keys
tmux-bridge keys codex Enter
tmux-bridge name <target> <label>
Label a pane (visible in tmux border)
tmux-bridge name %3 codex
tmux-bridge resolve <label>
Print pane target for a label
tmux-bridge resolve codex
tmux-bridge id
Print this pane's ID
tmux-bridge id
命令描述示例
tmux-bridge list
显示所有面板的目标标识、进程ID、命令、尺寸和标签
tmux-bridge list
tmux-bridge type <target> <text>
输入文本（不按回车）
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

Target Resolution

目标标识解析

Targets can be:
  • tmux native: 
    session:window.pane
    (e.g. 
    shared:0.1
    ), pane ID (
    %3
    ), or window index (
    0
    )
  • label: Any string set via 
    tmux-bridge name
    — resolved automatically
目标标识可以是：
  • tmux原生格式：
    session:window.pane
    （例如
    shared:0.1
    ）、面板ID（
    %3
    ）或窗口索引（
    0
    ）
  • 自定义标签：通过
    tmux-bridge name
    设置的任意字符串——会自动解析

Read-Act-Read Cycle

读取-操作-读取循环

Every interaction follows read → act → read. The CLI enforces this.
Sending a message to an agent:
bash
tmux-bridge read codex 20                    # 1. READ — satisfy read guard
tmux-bridge message codex 'Please review src/auth.ts'
                                              # 2. MESSAGE — auto-prepends sender info, no Enter
tmux-bridge read codex 20                    # 3. READ — verify text landed
tmux-bridge keys codex Enter                 # 4. KEYS — submit
每次交互都遵循读取 → 操作 → 读取的流程，CLI工具会强制执行此规则。
向Agent发送消息：
bash
tmux-bridge read codex 20                    # 1. 读取——满足读取防护要求
tmux-bridge message codex 'Please review src/auth.ts'
                                              # 2. 发送消息——自动添加发送方信息，不按回车
tmux-bridge read codex 20                    # 3. 读取——验证文本是否输入成功
tmux-bridge keys codex Enter                 # 4. 发送按键——提交消息

STOP. Do NOT read codex for a reply. The agent replies into YOUR pane.

停止操作。请勿读取codex面板等待回复，Agent会直接在您的面板中回复。


**Approving a prompt (non-agent pane):**
```bash
tmux-bridge read worker 10                   # 1. READ — see the prompt
tmux-bridge type worker "y"                  # 2. TYPE
tmux-bridge read worker 10                   # 3. READ — verify
tmux-bridge keys worker Enter                # 4. KEYS — submit
tmux-bridge read worker 20                   # 5. READ — see the result

**确认提示（非Agent面板）：**
```bash
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. 读取——查看结果

Messaging Convention

消息格式约定

The 
message
command auto-prepends sender info and location:
[tmux-bridge from:claude pane:%4 at:3:0.0] Please review src/auth.ts
The receiver gets: who sent it (
from
), the exact pane to reply to (
pane
), and the session/window location (
at
). When you see this header, reply using tmux-bridge to the pane ID from the header.
message
命令会自动在文本前添加发送方信息和位置：
[tmux-bridge from:claude pane:%4 at:3:0.0] Please review src/auth.ts
接收方会看到：发送方（
from
）、回复目标面板ID（
pane
）以及会话/窗口位置（
at
）。当您看到此头部信息时，请使用tmux-bridge向头部中的面板ID回复。

Agent-to-Agent Workflow

Agent间交互流程

bash
undefined
bash
undefined

1. Label yourself

1. 为自己的面板添加标签

tmux-bridge name "$(tmux-bridge id)" claude
tmux-bridge name "$(tmux-bridge id)" claude

2. Discover other panes

2. 发现其他面板

tmux-bridge list
tmux-bridge list

3. Send a message (read-act-read)

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
undefined
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
undefined

Example Conversation

交互示例

Agent A (claude) sends:
bash
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
Agent B (codex) sees in their prompt:
[tmux-bridge from:claude pane:%4 at:3:0.0] What is the test coverage for src/auth.ts?
Agent B replies using the pane ID from the header:
bash
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
Agent A（claude）发送消息：
bash
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
Agent B（codex）在自己的面板中看到：
[tmux-bridge from:claude pane:%4 at:3:0.0] What is the test coverage for src/auth.ts?
Agent B使用头部中的面板ID回复：
bash
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

Raw tmux Commands

原生tmux命令

Use these when you need direct tmux control beyond what tmux-bridge provides — session management, window navigation, creating panes, or low-level scripting.
当需要tmux-bridge未提供的直接控制能力时（如会话管理、窗口导航、创建面板或底层脚本编写），可使用这些命令。

Capture Output

捕获输出

bash
tmux capture-pane -t shared -p | tail -20    # Last 20 lines
tmux capture-pane -t shared -p -S -          # Entire scrollback
tmux capture-pane -t shared:0.0 -p           # Specific pane
bash
tmux capture-pane -t shared -p | tail -20    # 最后20行内容
tmux capture-pane -t shared -p -S -          # 所有滚动历史
tmux capture-pane -t shared:0.0 -p           # 指定面板的内容

Send Keys

发送按键

bash
tmux send-keys -t shared -l -- "text here"   # Type text (literal mode)
tmux send-keys -t shared Enter               # Press Enter
tmux send-keys -t shared Escape              # Press Escape
tmux send-keys -t shared C-c                 # Ctrl+C
tmux send-keys -t shared C-d                 # Ctrl+D (EOF)
For interactive TUIs, split text and Enter into separate sends:
bash
tmux send-keys -t shared -l -- "Please apply the patch"
sleep 0.1
tmux send-keys -t shared Enter
bash
tmux send-keys -t shared -l -- "text here"   # 输入文本（字面量模式）
tmux send-keys -t shared Enter               # 按回车
tmux send-keys -t shared Escape              # 按ESC键
tmux send-keys -t shared C-c                 # 按Ctrl+C
tmux send-keys -t shared C-d                 # 按Ctrl+D（EOF）
对于交互式TUI，建议将文本输入和回车操作分开执行：
bash
tmux send-keys -t shared -l -- "Please apply the patch"
sleep 0.1
tmux send-keys -t shared Enter

Panes and Windows

面板与窗口管理

bash
undefined
bash
undefined

Create panes (prefer over new windows)

创建面板（优先于新建窗口）

tmux split-window -h -t SESSION # Horizontal split tmux split-window -v -t SESSION # Vertical split tmux select-layout -t SESSION tiled # Re-balance
tmux split-window -h -t SESSION # 水平拆分 tmux split-window -v -t SESSION # 垂直拆分 tmux select-layout -t SESSION tiled # 重新平衡面板布局

Navigate

导航

tmux select-window -t shared:0 tmux select-pane -t shared:0.1 tmux list-windows -t shared
undefined
tmux select-window -t shared:0 tmux select-pane -t shared:0.1 tmux list-windows -t shared
undefined

Session Management

会话管理

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

Claude Code Patterns

Claude代码模式

bash
undefined
bash
undefined

Check if session needs input

检查会话是否需要输入

tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"
tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"

Approve a prompt

确认提示

tmux send-keys -t worker-3 'y' Enter
tmux send-keys -t worker-3 'y' Enter

Check all sessions

检查所有会话

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
undefined
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
undefined

Tips

注意事项

  • Read guard is enforced — you MUST read before every 
    type
    /
    keys
  • Every action clears the read mark — after 
    type
    , read again before 
    keys
  • Never wait or poll — agent panes reply via tmux-bridge into YOUR pane
  • Label panes early — easier than using 
    %N
    IDs
  • type
    uses literal mode     — special characters are typed as-is
  • read
    defaults to 50 lines     — pass a higher number for more context
  • Non-agent panes are the exception — you DO need to read them to see output
  • Use 
    capture-pane -p
    to print to stdout (essential for scripting)
  • Target format: 
    session:window.pane
    (e.g., 
    shared:0.0
    )
  • 读取防护机制是强制的——每次执行
    type
    /
    keys
    前必须先读取面板
  • 每次操作都会清除读取标记——执行
    type
    后，执行
    keys
    前需要重新读取
  • 请勿等待或轮询——Agent面板会通过tmux-bridge直接在您的面板中回复
  • 尽早为面板添加标签——比使用
    %N
    格式的ID更方便
  • type
    使用字面量模式    ——特殊字符会按原样输入
  • read
    默认读取50行    ——需要更多上下文时可传入更大的数值
  • 非Agent面板是例外——您需要读取这些面板来查看输出
  • 使用
    capture-pane -p
    将内容打印到标准输出（对脚本编写至关重要）
  • 目标格式：
    session:window.pane
    （例如
    shared:0.0
    ）