using-cmux
Original:🇺🇸 English
Translated
cmux ターミナル内での操作スキル。ペイン分割、サブエージェント起動・監視・結果回収、コマンド送信、画面読み取り、通知に使用。CMUX_* 環境変数が存在する場合にトリガーされる。
6installs
Sourcehummer98/using-cmux
Added on
NPX Install
npx skill4agent add hummer98/using-cmux using-cmuxTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →Using cmux
cmux はターミナルマルチプレクサ。ペイン分割、コマンド送信、画面読み取りを CLI 経由で操作する。
環境変数が存在すれば cmux 内で動作している。
CMUX_SOCKET_PATHQuick Orientation
bash
cmux identify # 自分のワークスペース・サーフェスを確認
cmux list-workspaces # 全ワークスペース一覧
cmux tree # トポロジー表示(階層構造)リソースは短縮 refs で参照する: , , , 。
で UUID 形式の出力も可能。
window:1workspace:2pane:3surface:4--id-format uuids注意:で複数行を送る場合はsendが必須。詳細は「send の改行ルール」を参照。send-key return
基本操作
| 操作 | コマンド |
|---|---|
| ペイン分割 | |
| 新ワークスペース | |
| コマンド送信 | |
| キー送信 | |
| 画面読み取り | |
| サーフェス/WS 終了 | |
| 一覧表示 | |
send の改行ルール
これは最も重要なルールである。
単一行コマンド: \n
で OK
\nbash
cmux send --surface surface:1 "echo hello\n"末尾の が Enter キーとして機能する。
\n複数行テキスト: send-key return
が必須
send-key return\nsend-key returnbash
# ✅ 正しい方法
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 は途中改行にならない
cmux send --surface surface:1 "line 1\nline 2\n"ルール: 末尾の 1個だけは Enter として機能する。文字列の途中に を入れても改行にはならない。
\n\n制御キーの送信
プロセス中断(Ctrl+C)などの制御キーは で送る。 では送れない。
send-keysendbash
# ✅ 正しい方法
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+cctrl+dctrl+zreturntabescapesend-key --helpcross-workspace 操作の注意(重要)
別ワークスペースのサーフェスを操作する場合、 ではなく を使う。
--surface--workspacebash
# ✅ 正しい方法 — --workspace で指定(focused surface に自動解決)
cmux send --workspace workspace:N "command\n"
cmux read-screen --workspace workspace:N
cmux send-key --workspace workspace:N return
# ❌ 間違い — --surface で他ワークスペースのサーフェスを指定
cmux send --surface surface:S "command\n" # → "Surface is not a terminal" エラー
cmux read-screen --surface surface:S # → 同上理由: は caller と同一ワークスペース内のサーフェスのみ有効。他ワークスペースのサーフェスを指定すると CLI は "Surface is not a terminal" エラーを返す。 はワークスペースの focused surface に自動解決され、cross-workspace でも正しく動作する。
--surface--workspaceペイン再利用の原則
新しいペイン/ワークスペースを作る前に、ユーザーが clear 済みの遊休ペインを探して再利用する。
bash
cmux list-pane-surfaces # 全サーフェス一覧
screen=$(cmux read-screen --surface surface:N) # 各サーフェスの状態を確認
# シェルプロンプト($ や ❯)のみ → 遊休 → 再利用可能遊休ペインがなければ通常通り / で作成する。
new-splitnew-workspaceサブエージェント操作パターン
サブエージェントを起動し、タスクを委任し、結果を回収する一連の手順。
重要: サブエージェントはメインエージェントとは別のワークスペースに配置する。同一ワークスペースだとペインの相互干渉が起きる。
Step 1: ワークスペース作成(または遊休ワークスペースの再利用)
bash
WS=$(cmux new-workspace --cwd $(pwd) | awk '{print $2}')
cmux rename-workspace --workspace $WS "Researcher-1" # 用途がわかる名前を付ける注意: PTY 遅延初期化問題(後述)により、ワークスペースを GUI 上で一度表示する必要がある場合がある。
Step 2: Claude Code 起動
bash
cmux send --workspace $WS "claude --dangerously-skip-permissions\n"は信頼できるタスクにのみ使うこと。--dangerously-skip-permissions
Step 3: Trust 検出 → 承認
起動直後に Trust 確認プロンプトが表示される場合がある。 でポーリングし、"trust" や "Yes, I trust" を検出したら承認:
read-screenbash
screen=$(cmux read-screen --workspace $WS)
# "trust" 検出 → 承認
cmux send-key --workspace $WS returnStep 4: 起動完了の検出
❯read-screen --workspace $WSStep 5: プロンプト送信
bash
# 単一行
cmux send --workspace $WS "指示テキスト\n"
cmux set-status $WS "調査中" --icon hammer # ステータスを設定
# 複数行(send-key return で改行)
cmux send --workspace $WS "1行目の指示"
cmux send-key --workspace $WS return
cmux send --workspace $WS "2行目の指示"
cmux send-key --workspace $WS returnStep 6: 完了検出
❯read-screen --workspace $WSStep 7: 結果回収
bash
cmux clear-status $WS # ステータスをクリア
result=$(cmux read-screen --workspace $WS --scrollback) # 全出力取得
cmux close-workspace --workspace $WS # 不要なら閉じるnew-workspace の PTY 遅延初期化問題(Issue #1472)
cmux new-workspaceselect-workspace症状
- → OK を返すがコマンドは実行されない(キューに留まる)
cmux send --surface surface:N - →
cmux read-screen --surface surface:NエラーSurface is not a terminal - ソケット API →
surface.send_textだが未配信queued: true - ソケット API →
surface.read_textTerminal surface not found
ワークアラウンド: AppleScript メニュークリック
macOS アクセシビリティ許可が必要(システム設定 → プライバシーとセキュリティ → アクセシビリティ)。
bash
# ワークスペース作成後に 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 初期化
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"注意: ソケット API のフォールバック
ソケット API / は、ターゲット surface の PTY が未初期化の場合、caller の surface にサイレントにフォールバックすることがある。レスポンスの を確認して意図した surface に送信されたか必ず検証すること。
surface.send_textsurface.read_textsurface_refread-screen トラブルシューティング
| 問題 | 対処 |
|---|---|
| 出力が空 / 古い | |
| 長い出力が切れる | |
| 特定行数だけ欲しい | |
| surface が見つからない | |
| PTY 遅延初期化問題。上記ワークアラウンド参照 |
read-screencmux refresh-surfacesロングラン実行の監視
dev server やビルドなど長時間プロセスは専用ペインに分離し、 で定期的に監視する。
read-screenbash
cmux new-split right # → surface:N
cmux send --surface surface:N "npm run dev\n"
# ポーリングで "ready" 等のキーワードを検出
screen=$(cmux read-screen --surface surface:N)通知
bash
# アプリ内通知(ペインハイライト、サイドバーバッジ。Cmd+Shift+U で移動)
cmux notify --title "完了" --body "ビルドが成功しました"
# macOS 通知センター(サウンド付き、別アプリ使用中でも表示)
osascript -e 'display notification "ビルド完了" with title "Claude" sound name "Glass"'使い分け: cmux 内で注意を引く → 、ユーザーが別アプリにいる → 。
cmux notifyosascriptステータス・プログレス表示
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 --helpcmux new-pane --type browser --url <url>環境変数
| 変数 | 説明 |
|---|---|
| cmux ソケットのパス。存在すれば cmux 内で動作中 |
| 現在のワークスペース ID |
| 現在のサーフェス ID |
よくあるミス
| ミス | 正しい方法 |
|---|---|
| 各行を個別に |
| UUID でサーフェスを指定する | 短縮 refs を使う: |
| サブエージェントを同一ワークスペースに配置 | 別ワークスペース ( |
| |
| Trust プロンプトを見逃してハングする | 起動後に |
| |
| |
| 遊休ペインがあるのに新しく split する | |
| ワークスペースに名前を付けない | |
コマンドクイックリファレンス
| コマンド | 説明 |
|---|---|
| 環境情報 / トポロジー表示 |
| 一覧表示 |
| ワークスペース・ペイン作成 |
| 入出力操作 |
| 画面バッファ強制更新 |
| リソース終了 |
| 選択・名前変更 |
| 通知・ステータス・進捗 |
| シグナル待機 |