跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

using-cmux

cmux ターミナル内での操作スキル。ペイン分割、サブエージェント起動・監視・結果回収、コマンド送信、画面読み取り、通知に使用。CMUX_* 環境変数が存在する場合にトリガーされる。

hummer98 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add hummer98/using-cmux --skill using-cmux

技能说明


name: using-cmux description: "cmux ターミナル内での操作スキル。ペイン分割、サブエージェント起動・監視・結果回収、コマンド送信、画面読み取り、通知に使用。CMUX_* 環境変数が存在する場合にトリガーされる。"

Using cmux

cmux はターミナルマルチプレクサ。ペイン分割、コマンド送信、画面読み取りを CLI 経由で操作する。 CMUX_SOCKET_PATH 環境変数が存在すれば cmux 内で動作している。

Quick Orientation

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

リソースは短縮 refs で参照する: window:1, workspace:2, pane:3, surface:4。 --id-format uuids で UUID 形式の出力も可能。

注意: cmux-send で複数行を送る場合は cmux-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 --surface surface:N [--scrollback]
サーフェス/WS 終了cmux close-surface / cmux close-workspace
一覧表示cmux list-panes / cmux list-pane-surfaces

send の改行ルール

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

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

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

末尾の \n が Enter キーとして機能する。

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

\n は改行として送信されない。各行を個別に送り、行間で cmux-send-key return を使う。

# ✅ 正しい方法
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"

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

制御キーの送信

プロセス中断(Ctrl+C)などの制御キーは cmux-send-key で送る。cmux-send では送れない。

# ✅ 正しい方法
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 等。cmux send-key --help で確認可能。

ラッパー使用の原則(重要)

cmux-read / cmux-send / cmux-send-key ラッパーを使う。 surface:N を渡すと自動的に正しいワークスペースを解決するため、別 workspace/window のサーフェスでも --surface だけで動く。

# ✅ 正しい方法 — surface ref から自動解決(window をまたいでも OK)
cmux-read --surface surface:N
cmux-send --surface surface:N "command\n"
cmux-send-key --surface surface:N return
# ❌ 間違い — 生の cmux コマンドは別 workspace/window のサーフェスで失敗
cmux read-screen --surface surface:S    # → "Surface is not a terminal" エラー
cmux send --surface surface:S "..."     # → 同上

理由: 生の cmux read-screen / cmux send / cmux send-key の --surface は caller と同一ワークスペース内のサーフェスのみ有効。ラッパーは内部で cmux tree --all --json から workspace を解決し --workspace 経由で呼び直すため、cross-window でも動作する。--workspace 形式はそのまま通過するので、new-workspace フロー(後述)でも統一して使える。

新しい surface をデフォルトで作る

別文脈での実行が必要なら、既存の surface を再利用せず cmux new-split で新規作成する。既存ペインの状態(実行中プロセス、未保存の作業)を破壊するリスクがあるため、再利用は危険。

トリガー: ユーザーが「別 surface で」「新しい surface で」「別ペインで」「split で」と指示した場合は、必ず new-split で新規作成する。現在の surface でそのまま実行してはいけない。

SURF=$(cmux new-split right | awk '{print $2}')
cmux-send --surface $SURF "command\n"
# 不要になったら閉じる
cmux close-surface --surface $SURF

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

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

配置方式の選択

方式利点注意
同一ワークスペース (new-split)PTY 遅延初期化問題を回避レイアウトが崩れたら cmux-grid で修復
別ワークスペース (new-workspace)close-workspace で一括終了、rename-workspace で識別しやすいPTY 遅延初期化問題の影響あり(後述)

Step 1a: 同一ワークスペースに配置(推奨)

SURF=$(cmux new-split right | awk '{print $2}')
cmux rename-tab --surface $SURF "Researcher-1"

Step 1b: 別ワークスペースに配置

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

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

Step 2: Claude Code 起動

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

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

Step 3: Trust 検出 → 承認

起動直後に Trust 確認プロンプトが表示される場合がある。cmux-read でポーリングし、"trust" や "Yes, I trust" を検出したら承認:

screen=$(cmux-read --workspace $WS)
# "trust" 検出 → 承認
cmux-send-key --workspace $WS return

Step 4: 起動完了の検出

❯ プロンプトが表示されるまで cmux-read --workspace $WS でポーリング。

Step 5: プロンプト送信

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

# 複数行(cmux-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

Step 6: 完了検出

❯ プロンプトの再表示を cmux-read --workspace $WS でポーリングして検出。

Step 7: 結果回収 & クリーンアップ

cmux clear-status $WS                                      # ステータスをクリア
result=$(cmux-read --workspace $WS --scrollback)  # 全出力取得

# クリーンアップ: Claude 終了 → ペイン閉じ
cmux-send --workspace $WS "/exit\n"
sleep 2
cmux close-workspace --workspace $WS                      # ワークスペースごと閉じる

重要: /exit だけでは Claude プロセスが終了するだけでペイン(surface)は残る。必ず close-workspace(または close-surface)でペインも閉じること。sleep 2 は /exit の処理完了を待つため。

new-workspace の PTY 遅延初期化問題(Issue #1472)

cmux new-workspace で作成したワークスペースのターミナル PTY は、GUI 上で一度表示されるまで起動しない。 select-workspace API だけでは不十分で、GUI 描画(SwiftUI レンダリング)が必要。

症状

  • cmux-send --surface surface:N → OK を返すがコマンドは実行されない(キューに留まる)
  • cmux-read --surface surface:N → Surface is not a terminal エラー
  • ソケット API surface.send_text → queued: true だが未配信
  • ソケット API surface.read_text → Terminal surface not found

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

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

# ワークスペース作成後に 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'] == '$
阅读完整来源 ↗