cmuxcmux/docs

API 參考

cmux 提供 CLI 工具和 Unix socket，用於程式化控制。每個指令都可以透過兩種介面使用。

Socket

建構路徑
正式版/tmp/cmux.sock
除錯版/tmp/cmux-debug.sock
標記的除錯版建構/tmp/cmux-debug-<tag>.sock

使用 CMUX_SOCKET_PATH 環境變數覆寫。每次呼叫傳送一個以換行符結尾的 JSON 請求：

{"id":"req-1","method":"workspace.list","params":{}}
// Response:
{"id":"req-1","ok":true,"result":{"workspaces":[...]}}
JSON socket 請求必須使用 method 和 params。不支援舊版 v1 JSON 格式，例如 {"command":"..."}。

存取模式

模式說明如何啟用
Off停用 socket設定 UI 或 CMUX_SOCKET_MODE=off
cmux processes only只有在 cmux 終端機內啟動的程序才能連線。設定 UI 中的預設模式
allowAll允許任何本機程序連線（不檢查血統關係）。僅限環境變數覆寫：CMUX_SOCKET_MODE=allowAll
在共用機器上，請使用「關閉」或「僅限 cmux 程序」模式。

CLI 選項

旗標說明
--socket PATH自訂 socket 路徑
--json以 JSON 格式輸出
--window ID指定特定視窗
--workspace ID指定特定工作區
--surface ID指定特定 surface
--id-format refs|uuids|both控制 JSON 輸出中的識別碼格式

工作區指令

list-workspaces

列出所有開啟的工作區。

CLI
cmux list-workspaces
cmux list-workspaces --json
Socket
{"id":"ws-list","method":"workspace.list","params":{}}

new-workspace

建立新的工作區。

CLI
cmux new-workspace
Socket
{"id":"ws-new","method":"workspace.create","params":{}}

select-workspace

切換到指定的工作區。

CLI
cmux select-workspace --workspace <id>
Socket
{"id":"ws-select","method":"workspace.select","params":{"workspace_id":"<id>"}}

current-workspace

取得目前活躍的工作區。

CLI
cmux current-workspace
cmux current-workspace --json
Socket
{"id":"ws-current","method":"workspace.current","params":{}}

close-workspace

關閉工作區。

CLI
cmux close-workspace --workspace <id>
Socket
{"id":"ws-close","method":"workspace.close","params":{"workspace_id":"<id>"}}

分割指令

new-split

建立新的分割窗格。方向：left、right、up、down。

CLI
cmux new-split right
cmux new-split down
Socket
{"id":"split-new","method":"surface.split","params":{"direction":"right"}}

list-surfaces

列出目前工作區中的所有 surface。

CLI
cmux list-surfaces
cmux list-surfaces --json
Socket
{"id":"surface-list","method":"surface.list","params":{}}

focus-surface

聚焦到指定的 surface。

CLI
cmux focus-surface --surface <id>
Socket
{"id":"surface-focus","method":"surface.focus","params":{"surface_id":"<id>"}}

輸入指令

send

向聚焦的終端機傳送文字輸入。

CLI
cmux send "echo hello"
cmux send "ls -la\n"
Socket
{"id":"send-text","method":"surface.send_text","params":{"text":"echo hello\n"}}

send-key

傳送按鍵。按鍵：enter、tab、escape、backspace、delete、up、down、left、right。

CLI
cmux send-key enter
Socket
{"id":"send-key","method":"surface.send_key","params":{"key":"enter"}}

send-surface

向指定的 surface 傳送文字。

CLI
cmux send-surface --surface <id> "command"
Socket
{"id":"send-surface","method":"surface.send_text","params":{"surface_id":"<id>","text":"command"}}

send-key-surface

向指定的 surface 傳送按鍵。

CLI
cmux send-key-surface --surface <id> enter
Socket
{"id":"send-key-surface","method":"surface.send_key","params":{"surface_id":"<id>","key":"enter"}}

通知指令

notify

傳送通知。

CLI
cmux notify --title "Title" --body "Body"
cmux notify --title "T" --subtitle "S" --body "B"
Socket
{"id":"notify","method":"notification.create","params":{"title":"Title","subtitle":"S","body":"Body"}}

list-notifications

列出所有通知。

CLI
cmux list-notifications
cmux list-notifications --json
Socket
{"id":"notif-list","method":"notification.list","params":{}}

clear-notifications

清除所有通知。

CLI
cmux clear-notifications
Socket
{"id":"notif-clear","method":"notification.clear","params":{}}

側邊欄中繼資料指令

為任何工作區設定側邊欄中的狀態標籤、進度條和日誌項目。適用於建構腳本、CI 整合，以及需要一目了然顯示狀態的 AI 程式碼代理。

set-status

設定側邊欄狀態標籤。使用唯一的 key，讓不同的工具可以管理各自的項目。

CLI
cmux set-status build "compiling" --icon hammer --color "#ff9500"
cmux set-status deploy "v1.2.3" --workspace workspace:2
Socket
set_status build compiling --icon=hammer --color=#ff9500 --tab=<workspace-uuid>

clear-status

依 key 移除側邊欄狀態項目。

CLI
cmux clear-status build
Socket
clear_status build --tab=<workspace-uuid>

list-status

列出工作區的所有側邊欄狀態項目。

CLI
cmux list-status
Socket
list_status --tab=<workspace-uuid>

set-progress

設定側邊欄中的進度條（0.0 到 1.0）。

CLI
cmux set-progress 0.5 --label "Building..."
cmux set-progress 1.0 --label "Done"
Socket
set_progress 0.5 --label=Building... --tab=<workspace-uuid>

clear-progress

清除側邊欄進度條。

CLI
cmux clear-progress
Socket
clear_progress --tab=<workspace-uuid>

log

在側邊欄附加日誌項目。級別：info、progress、success、warning、error。

CLI
cmux log "Build started"
cmux log --level error --source build "Compilation failed"
cmux log --level success -- "All 42 tests passed"
Socket
log --level=error --source=build --tab=<workspace-uuid> -- Compilation failed

clear-log

清除所有側邊欄日誌項目。

CLI
cmux clear-log
Socket
clear_log --tab=<workspace-uuid>

list-log

列出側邊欄日誌項目。

CLI
cmux list-log
cmux list-log --limit 5
Socket
list_log --limit=5 --tab=<workspace-uuid>

sidebar-state

傾印所有側邊欄中繼資料（cwd、git 分支、連接埠、狀態、進度、日誌）。

CLI
cmux sidebar-state
cmux sidebar-state --workspace workspace:2
Socket
sidebar_state --tab=<workspace-uuid>

工具指令

ping

檢查 cmux 是否正在執行且有回應。

CLI
cmux ping
Socket
{"id":"ping","method":"system.ping","params":{}}
// Response: {"id":"ping","ok":true,"result":{"pong":true}}

capabilities

列出可用的 socket 方法和目前的存取模式。

CLI
cmux capabilities
cmux capabilities --json
Socket
{"id":"caps","method":"system.capabilities","params":{}}

identify

顯示聚焦中的視窗/工作區/窗格/surface 情境。

CLI
cmux identify
cmux identify --json
Socket
{"id":"identify","method":"system.identify","params":{}}

環境變數

變數說明
CMUX_SOCKET_PATH覆寫 CLI 和整合所使用的 socket 路徑
CMUX_SOCKET_ENABLE強制啟用/停用 socket（1/0、true/false、on/off）
CMUX_SOCKET_MODE覆寫存取模式（cmuxOnly、allowAll、off）。也接受 cmux-only/cmux_only 和 allow-all/allow_all
CMUX_WORKSPACE_ID自動設定：目前工作區 ID
CMUX_SURFACE_ID自動設定：目前 surface ID
TERM_PROGRAM設定為 ghostty
TERM設定為 xterm-ghostty
舊版的 CMUX_SOCKET_MODE 值 full 和 notifications 仍然接受以保持相容性。

偵測 cmux

bash
# Prefer explicit socket path if set
SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"
[ -S "$SOCK" ] && echo "Socket available"

# Check for the CLI
command -v cmux &>/dev/null && echo "cmux available"

# In cmux-managed terminals these are auto-set
[ -n "${CMUX_WORKSPACE_ID:-}" ] && [ -n "${CMUX_SURFACE_ID:-}" ] && echo "Inside cmux surface"

# Distinguish from regular Ghostty
[ "$TERM_PROGRAM" = "ghostty" ] && [ -n "${CMUX_WORKSPACE_ID:-}" ] && echo "In cmux"

範例

Python 用戶端

python
import json
import os
import socket

SOCKET_PATH = os.environ.get("CMUX_SOCKET_PATH", "/tmp/cmux.sock")

def rpc(method, params=None, req_id=1):
    payload = {"id": req_id, "method": method, "params": params or {}}
    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
        sock.connect(SOCKET_PATH)
        sock.sendall(json.dumps(payload).encode("utf-8") + b"\n")
        return json.loads(sock.recv(65536).decode("utf-8"))

# List workspaces
print(rpc("workspace.list", req_id="ws"))

# Send notification
print(rpc(
    "notification.create",
    {"title": "Hello", "body": "From Python!"},
    req_id="notify"
))

Shell 腳本

bash
#!/bin/bash
SOCK="${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"

cmux_cmd() {
    printf "%s\n" "$1" | nc -U "$SOCK"
}

cmux_cmd '{"id":"ws","method":"workspace.list","params":{}}'
cmux_cmd '{"id":"notify","method":"notification.create","params":{"title":"Done","body":"Task complete"}}'

帶有通知的建構腳本

bash
#!/bin/bash
npm run build
if [ $? -eq 0 ]; then
    cmux notify --title "✓ Build Success" --body "Ready to deploy"
else
    cmux notify --title "✗ Build Failed" --body "Check the logs"
fi