API 레퍼런스

cmux는 프로그래밍 방식 제어를 위한 CLI 도구와 Unix 소켓을 모두 제공합니다. 모든 명령은 두 인터페이스를 통해 사용할 수 있습니다.

소켓

빌드	경로
릴리스	`/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 소켓 요청은 method와 params를 사용해야 합니다. {"command":"..."}와 같은 레거시 v1 JSON 페이로드는 지원되지 않습니다.

접근 모드

모드	설명	활성화 방법
Off	소켓 비활성화	설정 UI 또는 CMUX_SOCKET_MODE=off
cmux processes only	cmux 터미널 내에서 생성된 프로세스만 연결할 수 있습니다.	설정 UI의 기본 모드
allowAll	모든 로컬 프로세스의 연결을 허용합니다 (상위 프로세스 확인 없음).	환경 변수 오버라이드만: CMUX_SOCKET_MODE=allowAll

공유 머신에서는 끄기 또는 cmux 프로세스만을 사용하세요.

CLI 옵션

플래그	설명
`--socket PATH`	커스텀 소켓 경로
`--json`	JSON 형식으로 출력
`--window ID`	특정 창 대상 지정
`--workspace ID`	특정 워크스페이스 대상 지정
`--surface ID`	특정 서피스 대상 지정
`--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

현재 워크스페이스의 모든 서피스를 나열합니다.

CLI

cmux list-surfaces
cmux list-surfaces --json

Socket

{"id":"surface-list","method":"surface.list","params":{}}

focus-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

특정 서피스에 텍스트를 전송합니다.

CLI

cmux send-surface --surface <id> "command"

Socket

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

send-key-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

사이드바 상태 뱃지를 설정합니다. 다른 도구가 자체 항목을 관리할 수 있도록 고유 키를 사용하세요.

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

키로 사이드바 상태 항목을 제거합니다.

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

사용 가능한 소켓 메서드와 현재 접근 모드를 나열합니다.

CLI

cmux capabilities
cmux capabilities --json

Socket

{"id":"caps","method":"system.capabilities","params":{}}

identify

포커스된 창/워크스페이스/패널/서피스 컨텍스트를 표시합니다.

CLI

cmux identify
cmux identify --json

Socket

{"id":"identify","method":"system.identify","params":{}}

환경 변수

변수	설명
`CMUX_SOCKET_PATH`	CLI 및 통합에서 사용하는 소켓 경로 오버라이드
`CMUX_SOCKET_ENABLE`	소켓 강제 활성화/비활성화 (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`	자동 설정: 현재 서피스 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"
))

셸 스크립트

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