API Reference

cmux provides both a CLI tool and a Unix socket for programmatic control. Every command is available through both interfaces.

Socket

Build	Path
Release	`/tmp/cmux.sock`
Debug	`/tmp/cmux-debug.sock`

Override with the CMUX_SOCKET_PATH environment variable. Commands are newline-terminated JSON:

{"command": "command-name", "arg1": "value1"}
// Response:
{"success": true, "data": {...}}

Access modes

Mode	Description
Off	Socket disabled
Notifications only	Only notification commands allowed
Full control	All commands enabled

On shared machines, use “Notifications only” mode to prevent other users from controlling your terminals.

CLI options

Flag	Description
`--socket PATH`	Custom socket path
`--json`	Output in JSON format
`--workspace ID`	Target a specific workspace
`--surface ID`	Target a specific surface

Workspace commands

list-workspaces

List all open workspaces.

CLI

cmux list-workspaces
cmux list-workspaces --json

Socket

{"command": "list-workspaces"}

new-workspace

Create a new workspace.

CLI

cmux new-workspace

Socket

{"command": "new-workspace"}

select-workspace

Switch to a specific workspace.

CLI

cmux select-workspace --workspace <id>

Socket

{"command": "select-workspace", "id": "<id>"}

current-workspace

Get the currently active workspace.

CLI

cmux current-workspace
cmux current-workspace --json

Socket

{"command": "current-workspace"}

close-workspace

Close a workspace.

CLI

cmux close-workspace --workspace <id>

Socket

{"command": "close-workspace", "id": "<id>"}

Split commands

new-split

Create a new split pane. Directions: left, right, up, down.

CLI

cmux new-split right
cmux new-split down

Socket

{"command": "new-split", "direction": "right"}

list-surfaces

List all surfaces in the current workspace.

CLI

cmux list-surfaces
cmux list-surfaces --json

Socket

{"command": "list-surfaces"}

focus-surface

Focus a specific surface.

CLI

cmux focus-surface --surface <id>

Socket

{"command": "focus-surface", "id": "<id>"}

Input commands

send

Send text input to the focused terminal.

CLI

cmux send "echo hello"
cmux send "ls -la\n"

Socket

{"command": "send", "text": "echo hello\n"}

send-key

Send a key press. Keys: enter, tab, escape, backspace, delete, up, down, left, right.

CLI

cmux send-key enter

Socket

{"command": "send-key", "key": "enter"}

send-surface

Send text to a specific surface.

CLI

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

Socket

{"command": "send-surface", "id": "<id>", "text": "command"}

send-key-surface

Send a key press to a specific surface.

CLI

cmux send-key-surface --surface <id> enter

Socket

{"command": "send-key-surface", "id": "<id>", "key": "enter"}

Notification commands

notify

Send a notification.

CLI

cmux notify --title "Title" --body "Body"
cmux notify --title "T" --subtitle "S" --body "B"

Socket

{"command": "notify", "title": "Title",
 "subtitle": "S", "body": "Body"}

list-notifications

List all notifications.

CLI

cmux list-notifications
cmux list-notifications --json

Socket

{"command": "list-notifications"}

clear-notifications

Clear all notifications.

CLI

cmux clear-notifications

Socket

{"command": "clear-notifications"}

Utility commands

ping

Check if cmux is running and responsive.

CLI

cmux ping

Socket

{"command": "ping"}
// Response: {"success": true, "pong": true}

Environment variables

Variable	Description
`CMUX_SOCKET_PATH`	Override the default socket path
`CMUX_SOCKET_ENABLE`	Enable/disable socket (`1`/`0`)
`CMUX_SOCKET_MODE`	Override access mode (`full`, `notifications`, `off`)
`CMUX_WORKSPACE_ID`	Auto-set: current workspace ID
`CMUX_SURFACE_ID`	Auto-set: current surface ID
`TERM_PROGRAM`	Set to `ghostty`
`TERM`	Set to `xterm-ghostty`

Environment variables override app settings. Use the socket check to distinguish cmux from regular Ghostty.

Detecting cmux

bash

# Check for the socket
[ -S /tmp/cmux.sock ] && echo "In cmux"

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

# Distinguish from regular Ghostty
[ "$TERM_PROGRAM" = "ghostty" ] && [ -S /tmp/cmux.sock ] && echo "In cmux"

Examples

Python client

python

import socket, json

def send_command(cmd):
    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    sock.connect('/tmp/cmux.sock')
    sock.send(json.dumps(cmd).encode() + b'\n')
    response = sock.recv(4096).decode()
    sock.close()
    return json.loads(response)

# List workspaces
print(send_command({"command": "list-workspaces"}))

# Send notification
send_command({
    "command": "notify",
    "title": "Hello",
    "body": "From Python!"
})

Shell script

bash

#!/bin/bash
cmux_cmd() {
    echo "$1" | nc -U /tmp/cmux.sock
}

cmux_cmd '{"command": "list-workspaces"}'
cmux_cmd '{"command": "notify", "title": "Done", "body": "Task complete"}'

Build script with notification

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