using-cmux

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Using cmux

使用cmux

cmux はターミナルマルチプレクサ。ペイン分割、コマンド送信、画面読み取りを CLI 経由で操作する。

CMUX_SOCKET_PATH

環境変数が存在すれば cmux 内で動作している。

cmux是一款终端复用器，可通过CLI进行面板分割、命令发送、屏幕读取等操作。若存在

CMUX_SOCKET_PATH

环境变量，则表示当前在cmux内运行。

Quick Orientation

快速入门

bash

cmux identify                    # 自分のワークスペース・サーフェスを確認
cmux list-workspaces             # 全ワークスペース一覧
cmux tree                        # トポロジー表示（階層構造）

リソースは短縮 refs で参照する:

window:1

workspace:2

pane:3

surface:4

。

--id-format uuids

で UUID 形式の出力も可能。

注意:
send
で複数行を送る場合は
send-key return
が必須。詳細は「send の改行ルール」を参照。

bash

cmux identify                    # 确认自己的工作区与界面
cmux list-workspaces             # 查看所有工作区列表
cmux tree                        # 显示拓扑结构（层级结构）

资源可通过短引用进行访问：

window:1

workspace:2

pane:3

surface:4

。使用

--id-format uuids

可输出UUID格式的资源标识。

注意：使用
send
发送多行内容时，必须搭配
send-key return
。详情请参考「send的换行规则」。

基本操作

操作	コマンド
ペイン分割	`cmux new-split right` (left/up/down も可)
新ワークスペース	`cmux new-workspace --cwd $(pwd)`
コマンド送信	`cmux send --surface surface:N "command\n"`
キー送信	`cmux send-key --surface surface:N return` / `ctrl+c` / `ctrl+d`
画面読み取り	`cmux read-screen --surface surface:N [--scrollback]`
サーフェス/WS 終了	`cmux close-surface` / `cmux close-workspace`
一覧表示	`cmux list-panes` / `cmux list-pane-surfaces`

操作	命令
面板分割	`cmux new-split right` （也可使用left/up/down）
创建新工作区	`cmux new-workspace --cwd $(pwd)`
发送命令	`cmux send --surface surface:N "command\n"`
发送按键	`cmux send-key --surface surface:N return` / `ctrl+c` / `ctrl+d`
读取屏幕内容	`cmux read-screen --surface surface:N [--scrollback]`
关闭界面/工作区	`cmux close-surface` / `cmux close-workspace`
查看列表	`cmux list-panes` / `cmux list-pane-surfaces`

send の改行ルール

send的换行规则

これは最も重要なルールである。

这是最重要的规则。

単一行コマンド:

\n

で OK

单行命令：使用

\n

即可

bash

cmux send --surface surface:1 "echo hello\n"

末尾の

\n

が Enter キーとして機能する。

bash

cmux send --surface surface:1 "echo hello\n"

末尾的

\n

将作为回车键生效。

複数行テキスト:

send-key return

が必須

多行文本：必须使用

send-key return

\n

は改行として送信されない。各行を個別に送り、行間で

send-key return

を使う。

bash

undefined

\n

不会被作为换行符发送。需逐行发送内容，并在行间使用

send-key return

。

bash

undefined

✅ 正しい方法

✅ 正确方法

cmux send --surface surface:1 "line 1" cmux send-key --surface surface:1 return cmux send --surface surface:1 "line 2" cmux send-key --surface surface:1 return

❌ 間違い — \n は途中改行にならない

❌ 错误方法 — \n不会成为中途换行

cmux send --surface surface:1 "line 1\nline 2\n"


**ルール**: 末尾の `\n` 1個だけは Enter として機能する。文字列の途中に `\n` を入れても改行にはならない。

cmux send --surface surface:1 "line 1\nline 2\n"


**规则**：仅末尾的一个`\n`会作为回车键生效，字符串中间的`\n`不会被解析为换行。

制御キーの送信

控制键的发送

プロセス中断（Ctrl+C）などの制御キーは send-key
で送る。

send

では送れない。

bash

undefined

中断进程（Ctrl+C）等控制键需通过**

send-key

**发送，无法通过

send

发送。

bash

undefined

✅ 正しい方法

✅ 正确方法

cmux send-key --surface surface:N ctrl+c

❌ 間違い — リテラルテキストが送られるだけ

❌ 错误方法 — 仅会发送字面文本

cmux send --surface surface:N "C-c" cmux send --surface surface:N "\x03" cmux send-key --surface surface:N "C-c" # → Unknown key エラー


キー名は `ctrl+c`, `ctrl+d`, `ctrl+z`, `return`, `tab`, `escape` 等。`send-key --help` で確認可能。

cmux send --surface surface:N "C-c" cmux send --surface surface:N "\x03" cmux send-key --surface surface:N "C-c" # → 出现Unknown key错误


可用的键名包括`ctrl+c`, `ctrl+d`, `ctrl+z`, `return`, `tab`, `escape`等，可通过`send-key --help`查看完整列表。

cross-workspace 操作の注意（重要）

跨工作区操作注意事项（重要）

別ワークスペースのサーフェスを操作する場合、--surface
ではなく
--workspace
を使う。

bash

undefined

操作其他工作区的界面时，需使用
--workspace
而非
--surface
。

bash

undefined

✅ 正しい方法 — --workspace で指定（focused surface に自動解決）

✅ 正确方法 — 使用--workspace指定（自动匹配聚焦的界面）

cmux send --workspace workspace:N "command\n" cmux read-screen --workspace workspace:N cmux send-key --workspace workspace:N return

❌ 間違い — --surface で他ワークスペースのサーフェスを指定

❌ 错误方法 — 使用--surface指定其他工作区的界面

cmux send --surface surface:S "command\n" # → "Surface is not a terminal" エラー cmux read-screen --surface surface:S # → 同上


**理由**: `--surface` は caller と同一ワークスペース内のサーフェスのみ有効。他ワークスペースのサーフェスを指定すると CLI は "Surface is not a terminal" エラーを返す。`--workspace` はワークスペースの focused surface に自動解決され、cross-workspace でも正しく動作する。

cmux send --surface surface:S "command\n" # → 出现"Surface is not a terminal"错误 cmux read-screen --surface surface:S # → 同上


**原因**：`--surface`仅对与调用者同一工作区内的界面有效。若指定其他工作区的界面，CLI会返回"Surface is not a terminal"错误。`--workspace`会自动匹配工作区的聚焦界面，跨工作区操作时可正常运行。

ペイン再利用の原則

面板复用原则

新しいペイン/ワークスペースを作る前に、ユーザーが clear 済みの遊休ペインを探して再利用する。

bash

cmux list-pane-surfaces                          # 全サーフェス一覧
screen=$(cmux read-screen --surface surface:N)   # 各サーフェスの状態を確認

在创建新面板/工作区前，应先查找用户已清空的闲置面板进行复用。

bash

cmux list-pane-surfaces                          # 查看所有界面列表
screen=$(cmux read-screen --surface surface:N)   # 确认各界面的状态

シェルプロンプト（$ や ❯）のみ → 遊休 → 再利用可能

仅显示Shell提示符（$ 或 ❯）→ 属于闲置状态 → 可复用


遊休ペインがなければ通常通り `new-split` / `new-workspace` で作成する。


若没有闲置面板，则正常使用`new-split`/`new-workspace`创建新面板。

サブエージェント操作パターン

子Agent操作流程

サブエージェントを起動し、タスクを委任し、結果を回収する一連の手順。

重要: サブエージェントはメインエージェントとは別のワークスペースに配置する。同一ワークスペースだとペインの相互干渉が起きる。

以下是启动子Agent、分配任务并回收结果的一系列步骤。

重要：子Agent需放置在与主Agent不同的工作区中，同一工作区会导致面板相互干扰。

Step 1: ワークスペース作成（または遊休ワークスペースの再利用）

Step 1：创建工作区（或复用闲置工作区）

bash

WS=$(cmux new-workspace --cwd $(pwd) | awk '{print $2}')
cmux rename-workspace --workspace $WS "Researcher-1"  # 用途がわかる名前を付ける

注意: PTY 遅延初期化問題（後述）により、ワークスペースを GUI 上で一度表示する必要がある場合がある。

bash

WS=$(cmux new-workspace --cwd $(pwd) | awk '{print $2}')
cmux rename-workspace --workspace $WS "Researcher-1"  # 命名为便于识别的名称

注意：由于PTY延迟初始化问题（下文详述），有时需在GUI中显示一次工作区才能正常使用。

Step 2: Claude Code 起動

Step 2：启动Claude Code

bash

cmux send --workspace $WS "claude --dangerously-skip-permissions\n"

--dangerously-skip-permissions
は信頼できるタスクにのみ使うこと。

bash

cmux send --workspace $WS "claude --dangerously-skip-permissions\n"

--dangerously-skip-permissions
仅可用于可信任的任务。

Step 3: Trust 検出 → 承認

Step 3：检测Trust提示 → 确认授权

起動直後に Trust 確認プロンプトが表示される場合がある。

read-screen

でポーリングし、"trust" や "Yes, I trust" を検出したら承認:

bash

screen=$(cmux read-screen --workspace $WS)

启动后可能会显示Trust确认提示，需通过

read-screen

轮询检测，若发现"trust"或"Yes, I trust"则进行授权：

bash

screen=$(cmux read-screen --workspace $WS)

"trust" 検出 → 承認

检测到"trust" → 执行授权

cmux send-key --workspace $WS return

undefined

cmux send-key --workspace $WS return

undefined

Step 4: 起動完了の検出

Step 4：检测启动完成

❯

プロンプトが表示されるまで

read-screen --workspace $WS

でポーリング。

通过

read-screen --workspace $WS

轮询，直到出现

❯

提示符。

Step 5: プロンプト送信

Step 5：发送提示词

bash

undefined

bash

undefined

単一行

单行内容

cmux send --workspace $WS "指示テキスト\n" cmux set-status $WS "調査中" --icon hammer # ステータスを設定

cmux send --workspace $WS "指示文本\n" cmux set-status $WS "调查中" --icon hammer # 设置状态

複数行（send-key return で改行）

多行内容（使用send-key return换行）

cmux send --workspace $WS "1行目の指示" cmux send-key --workspace $WS return cmux send --workspace $WS "2行目の指示" cmux send-key --workspace $WS return

undefined

cmux send --workspace $WS "第1行指示" cmux send-key --workspace $WS return cmux send --workspace $WS "第2行指示" cmux send-key --workspace $WS return

undefined

Step 6: 完了検出

Step 6：检测完成状态

❯

プロンプトの再表示を

read-screen --workspace $WS

でポーリングして検出。

通过

read-screen --workspace $WS

轮询，检测

❯

提示符的再次出现。

Step 7: 結果回収

Step 7：回收结果

bash

cmux clear-status $WS                                      # ステータスをクリア
result=$(cmux read-screen --workspace $WS --scrollback)  # 全出力取得
cmux close-workspace --workspace $WS                      # 不要なら閉じる

bash

cmux clear-status $WS                                      # 清除状态
result=$(cmux read-screen --workspace $WS --scrollback)  # 获取全部输出
cmux close-workspace --workspace $WS                      # 若无需保留则关闭工作区

new-workspace の PTY 遅延初期化問題（Issue #1472）

new-workspace的PTY延迟初始化问题（Issue #1472）

cmux new-workspace

で作成したワークスペースのターミナル PTY は、GUI 上で一度表示されるまで起動しない。

select-workspace

API だけでは不十分で、GUI 描画（SwiftUI レンダリング）が必要。

通过

cmux new-workspace

创建的工作区，其终端PTY需在GUI中显示一次后才会启动。仅使用

select-workspace

API无法解决，必须进行GUI渲染（SwiftUI渲染）。

症状

```
cmux send --surface surface:N
```
→ OK を返すがコマンドは実行されない（キューに留まる）

cmux read-screen --surface surface:N

→

Surface is not a terminal

エラー

ソケット API
```
surface.send_text
```
→
```
queued: true
```
だが未配信

ソケット API

surface.read_text

→

Terminal surface not found

```
cmux send --surface surface:N
```
→ 返回OK但命令未执行（停留在队列中）

cmux read-screen --surface surface:N

→ 出现

Surface is not a terminal

错误

Socket API
```
surface.send_text
```
→ 返回
```
queued: true
```
但未发送

Socket API

surface.read_text

→ 返回

Terminal surface not found

ワークアラウンド: AppleScript メニュークリック

解决方法：AppleScript菜单点击

macOS アクセシビリティ許可が必要（システム設定 → プライバシーとセキュリティ → アクセシビリティ）。

bash

undefined

需要macOS辅助功能权限（系统设置→隐私与安全性→辅助功能）。

bash

undefined

ワークスペース作成後に GUI 表示を強制する

创建工作区后强制在GUI中显示

WS=$(cmux new-workspace --cwd $(pwd) | awk '{print $2}')

ワークスペースのインデックスを取得

获取工作区索引

WS_INDEX=$(cmux tree --json | python3 -c " import json, sys data = json.load(sys.stdin) for w in data['windows']: for ws in w['workspaces']: if ws['ref'] == '$WS': print(ws['index'] + 1)")

AppleScript でメニュークリック → PTY 初期化

通过AppleScript点击菜单 → 初始化PTY

osascript -e " tell application "System Events" tell process "cmux" click menu item "ワークスペース $WS_INDEX" of menu 1 of menu bar item "表示" of menu bar 1 end tell end tell" sleep 2

元のワークスペースに戻る

返回原工作区

ORIG_INDEX=1 # 元のワークスペースの index+1 osascript -e " tell application "System Events" tell process "cmux" click menu item "ワークスペース $ORIG_INDEX" of menu 1 of menu bar item "表示" of menu bar 1 end tell end tell"

undefined

ORIG_INDEX=1 # 原工作区的index+1 osascript -e " tell application "System Events" tell process "cmux" click menu item "ワークスペース $ORIG_INDEX" of menu 1 of menu bar item "表示" of menu bar 1 end tell end tell"

undefined

注意: ソケット API のフォールバック

注意：Socket API的回退机制

ソケット API

surface.send_text

surface.read_text

は、ターゲット surface の PTY が未初期化の場合、caller の surface にサイレントにフォールバックすることがある。レスポンスの

surface_ref

を確認して意図した surface に送信されたか必ず検証すること。

当目标界面的PTY未初始化时，Socket API

surface.send_text

surface.read_text

可能会静默回退到调用者的界面。务必检查响应中的

surface_ref

，确认内容是否发送到了目标界面。

read-screen トラブルシューティング

read-screen故障排查

問題	対処
出力が空 / 古い	`cmux refresh-surfaces` してから再読み取り
長い出力が切れる	`--scrollback` を追加
特定行数だけ欲しい	`--lines N` で行数指定
surface が見つからない	`cmux list-pane-surfaces` で refs を再確認
`Surface is not a terminal`	PTY 遅延初期化問題。上記ワークアラウンド参照

read-screen

の結果がおかしい場合は

cmux refresh-surfaces

→ 再読み取りの順で試す。

问题	解决方法
输出为空/内容陈旧	执行 `cmux refresh-surfaces` 后重新读取
长输出被截断	添加 `--scrollback` 参数
仅需特定行数	使用 `--lines N` 指定行数
无法找到界面	通过 `cmux list-pane-surfaces` 重新确认引用标识
出现 `Surface is not a terminal`	属于PTY延迟初始化问题，参考上述解决方法

若

read-screen

结果异常，请按

cmux refresh-surfaces

→重新读取的顺序尝试。

ロングラン実行の監視

长时运行任务的监控

dev server やビルドなど長時間プロセスは専用ペインに分離し、

read-screen

で定期的に監視する。

bash

cmux new-split right              # → surface:N
cmux send --surface surface:N "npm run dev\n"

开发服务器、构建等长时进程需分离到专用面板，并通过

read-screen

定期监控。

bash

cmux new-split right              # → surface:N
cmux send --surface surface:N "npm run dev\n"

ポーリングで "ready" 等のキーワードを検出

通过轮询检测"ready"等关键词

screen=$(cmux read-screen --surface surface:N)

undefined

screen=$(cmux read-screen --surface surface:N)

undefined

通知

bash

undefined

bash

undefined

アプリ内通知（ペインハイライト、サイドバーバッジ。Cmd+Shift+U で移動）

应用内通知（面板高亮、侧边栏徽章，使用Cmd+Shift+U跳转）

cmux notify --title "完了" --body "ビルドが成功しました"

cmux notify --title "完成" --body "构建已成功"

macOS 通知センター（サウンド付き、別アプリ使用中でも表示）

macOS通知中心（带声音，即使在使用其他应用时也会显示）

osascript -e 'display notification "ビルド完了" with title "Claude" sound name "Glass"'


使い分け: cmux 内で注意を引く → `cmux notify`、ユーザーが別アプリにいる → `osascript`。

osascript -e 'display notification "构建完成" with title "Claude" sound name "Glass"'


使用场景区分：需在cmux内提醒用户→使用`cmux notify`；用户在使用其他应用→使用`osascript`。

ステータス・プログレス表示

状态与进度显示

bash

cmux set-status mykey "作業中" --icon hammer --color "#0099ff"  # サイドバーに表示
cmux clear-status mykey
cmux set-progress 0.5 --label "ビルド中..."                     # プログレスバー（0.0〜1.0）
cmux clear-progress

bash

cmux set-status mykey "工作中" --icon hammer --color "#0099ff"  # 在侧边栏显示
cmux clear-status mykey
cmux set-progress 0.5 --label "构建中..."                     # 进度条（取值范围0.0~1.0）
cmux clear-progress

ブラウザ

浏览器功能

cmux にはブラウザ自動化機能もある。詳細は

cmux browser --help

を参照。

cmux new-pane --type browser --url <url>

でブラウザペインを作成できる。

cmux还具备浏览器自动化功能，详情请参考

cmux browser --help

。可通过

cmux new-pane --type browser --url <url>

创建浏览器面板。

環境変数

环境变量

変数	説明
`CMUX_SOCKET_PATH`	cmux ソケットのパス。存在すれば cmux 内で動作中
`CMUX_WORKSPACE_ID`	現在のワークスペース ID
`CMUX_SURFACE_ID`	現在のサーフェス ID

变量	说明
`CMUX_SOCKET_PATH`	cmux套接字路径，若存在则表示当前在cmux内运行
`CMUX_WORKSPACE_ID`	当前工作区ID
`CMUX_SURFACE_ID`	当前界面ID

よくあるミス

常见错误

ミス	正しい方法
`send "line1\nline2\n"` で複数行を送る	各行を個別に `send` し、行間で `send-key return` を使う
UUID でサーフェスを指定する	短縮 refs を使う: `surface:1` , `pane:2`
サブエージェントを同一ワークスペースに配置	別ワークスペース ( `new-workspace` ) に配置する
`read-screen` の結果が空で諦める	`refresh-surfaces` を実行してからリトライ
Trust プロンプトを見逃してハングする	起動後に `read-screen` でポーリングして検出する
`--surface` で他ワークスペースを操作	`--workspace` を使う（cross-workspace 操作の注意参照）
`send "C-c"` や `send "\x03"` で Ctrl+C を送る	`send-key ctrl+c` を使う（制御キーの送信参照）
遊休ペインがあるのに新しく split する	`list-pane-surfaces` + `read-screen` で遊休ペインを探して再利用する
ワークスペースに名前を付けない	`rename-workspace` で用途を示す名前を付ける

错误操作	正确方法
使用 `send "line1\nline2\n"` 发送多行内容	逐行使用 `send` 发送，并在行间使用 `send-key return`
使用UUID指定界面	使用短引用： `surface:1` , `pane:2`
将子Agent放置在同一工作区	放置在独立工作区（ `new-workspace` ）
`read-screen` 结果为空就放弃	执行 `refresh-surfaces` 后重试
遗漏Trust提示导致任务挂起	启动后通过 `read-screen` 轮询检测
使用 `--surface` 操作其他工作区	使用 `--workspace` （参考跨工作区操作注意事项）
使用 `send "C-c"` 或 `send "\x03"` 发送Ctrl+C	使用 `send-key ctrl+c` （参考控制键的发送）
存在闲置面板却创建新面板	通过 `list-pane-surfaces` + `read-screen` 寻找闲置面板复用
不给工作区命名	使用 `rename-workspace` 设置能体现用途的名称

コマンドクイックリファレンス

命令速查

コマンド	説明
`identify` / `tree`	環境情報 / トポロジー表示
`list-workspaces` / `list-panes` / `list-pane-surfaces`	一覧表示
`new-workspace` / `new-split <dir>`	ワークスペース・ペイン作成
`send` / `send-key` / `read-screen`	入出力操作
`refresh-surfaces`	画面バッファ強制更新
`close-surface` / `close-workspace`	リソース終了
`select-workspace` / `rename-workspace` / `rename-tab`	選択・名前変更
`notify` / `set-status` / `set-progress`	通知・ステータス・進捗
`wait-for`	シグナル待機

命令	说明
`identify` / `tree`	显示环境信息/拓扑结构
`list-workspaces` / `list-panes` / `list-pane-surfaces`	显示各类资源列表
`new-workspace` / `new-split <dir>`	创建工作区/面板
`send` / `send-key` / `read-screen`	输入输出操作
`refresh-surfaces`	强制更新屏幕缓冲区
`close-surface` / `close-workspace`	关闭资源
`select-workspace` / `rename-workspace` / `rename-tab`	选择/重命名操作
`notify` / `set-status` / `set-progress`	通知/状态/进度设置
`wait-for`	等待信号

using-cmux

Original

Translation

Using cmux

使用cmux

Quick Orientation

快速入门

基本操作

基本操作

send の改行ルール

send的换行规则

単一行コマンド: \n で OK

单行命令：使用\n即可

複数行テキスト: send-key return が必須

多行文本：必须使用send-key return

✅ 正しい方法

✅ 正确方法

❌ 間違い — \n は途中改行にならない

❌ 错误方法 — \n不会成为中途换行

制御キーの送信

控制键的发送

✅ 正しい方法

✅ 正确方法

❌ 間違い — リテラルテキストが送られるだけ

❌ 错误方法 — 仅会发送字面文本

cross-workspace 操作の注意（重要）

跨工作区操作注意事项（重要）

✅ 正しい方法 — --workspace で指定（focused surface に自動解決）

✅ 正确方法 — 使用--workspace指定（自动匹配聚焦的界面）

❌ 間違い — --surface で他ワークスペースのサーフェスを指定

❌ 错误方法 — 使用--surface指定其他工作区的界面

ペイン再利用の原則

面板复用原则

シェルプロンプト（$ や ❯）のみ → 遊休 → 再利用可能

仅显示Shell提示符（$ 或 ❯）→ 属于闲置状态 → 可复用

サブエージェント操作パターン

子Agent操作流程

Step 1: ワークスペース作成（または遊休ワークスペースの再利用）

Step 1：创建工作区（或复用闲置工作区）

Step 2: Claude Code 起動

Step 2：启动Claude Code

Step 3: Trust 検出 → 承認

Step 3：检测Trust提示 → 确认授权

"trust" 検出 → 承認

检测到"trust" → 执行授权

Step 4: 起動完了の検出

Step 4：检测启动完成

Step 5: プロンプト送信

Step 5：发送提示词

単一行

单行内容

複数行（send-key return で改行）

多行内容（使用send-key return换行）

Step 6: 完了検出

Step 6：检测完成状态

Step 7: 結果回収

Step 7：回收结果

new-workspace の PTY 遅延初期化問題（Issue #1472）

new-workspace的PTY延迟初始化问题（Issue #1472）

症状

症状

ワークアラウンド: AppleScript メニュークリック

解决方法：AppleScript菜单点击

ワークスペース作成後に GUI 表示を強制する

创建工作区后强制在GUI中显示

ワークスペースのインデックスを取得

获取工作区索引

AppleScript でメニュークリック → PTY 初期化

通过AppleScript点击菜单 → 初始化PTY

元のワークスペースに戻る

返回原工作区

注意: ソケット API のフォールバック

注意：Socket API的回退机制

read-screen トラブルシューティング

read-screen故障排查

ロングラン実行の監視

长时运行任务的监控

ポーリングで "ready" 等のキーワードを検出

通过轮询检测"ready"等关键词

通知

単一行コマンド:
`\n`
で OK

单行命令：使用
`\n`
即可

複数行テキスト:
`send-key return`
が必須

多行文本：必须使用
`send-key return`