API 参考

cmux 提供 CLI 工具和 Unix socket 两种编程控制方式。每个命令都可以通过两种接口使用。

Socket

构建版本	路径
Release	`/tmp/cmux.sock`
Debug	`/tmp/cmux-debug.sock`
带标签的 Debug 构建	`/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	Settings UI 或 CMUX_SOCKET_MODE=off
cmux processes only	仅允许在 cmux 终端内启动的进程连接。	Settings UI 中的默认模式
allowAll	允许任何本地进程连接（不检查进程来源）。	仅通过环境变量覆盖：CMUX_SOCKET_MODE=allowAll

在共享机器上，请使用 Off 或 cmux processes only。

CLI 选项

Flag	描述
`--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 coding agent。

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