smux

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

keys

to a pane unless you have read it first.

```
tmux-bridge read <target>
```
marks the pane as "read"
```
tmux-bridge type/keys <target>
```
checks for that mark — errors if you haven't read
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

命令操作面板。

```
tmux-bridge read <target>
```
会将面板标记为“已读取”
```
tmux-bridge type/keys <target>
```
会检查该标记——若未读取则报错
成功执行
```
type
```
/
```
keys
```
后，标记会被清除——下次交互前必须重新读取

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

Command Reference

命令参考

Command	Description	Example
`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

2. Discover other panes

2. 发现其他面板

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

Check if session needs input

检查会话是否需要输入

Approve a prompt

确认提示

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
```
）

smux

Original

Translation

smux

smux

tmux-bridge — Cross-Pane Communication

tmux-bridge — 跨面板通信

DO NOT WAIT OR POLL

请勿等待或轮询

Read Guard

读取防护机制

Command Reference

命令参考

Target Resolution

目标标识解析

Read-Act-Read Cycle

读取-操作-读取循环

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

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

Messaging Convention

消息格式约定

Agent-to-Agent Workflow

Agent间交互流程

1. Label yourself

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

2. Discover other panes

2. 发现其他面板

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

3. 发送消息（遵循读取-操作-读取流程）

Example Conversation

交互示例

Raw tmux Commands

原生tmux命令

Capture Output

捕获输出

Send Keys

发送按键

Panes and Windows

面板与窗口管理

Create panes (prefer over new windows)

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

Navigate

导航

Session Management

会话管理

Claude Code Patterns

Claude代码模式

Check if session needs input

检查会话是否需要输入

Approve a prompt

确认提示

Check all sessions

检查所有会话

Tips

注意事项