Socket API

cmuxterm exposes a Unix socket for programmatic control, enabling automation and integration with tools like Claude Code.

Socket Location

Build	Socket Path
Release	`/tmp/cmuxterm.sock`
Debug	`/tmp/cmuxterm-debug.sock`

You can override the path with the CMUX_SOCKET_PATH environment variable.

Access Modes

cmuxterm has three access modes, configurable in Settings:

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.

Protocol

Commands are sent as newline-terminated JSON:

{"command": "command-name", "arg1": "value1"}

Responses are newline-terminated JSON:

{"success": true, "data": {...}}
{"success": false, "error": "Error message"}

Commands Reference

Tab Management

list-tabs

List all open tabs.

{"command": "list-tabs"}

Response:

{
  "success": true,
  "tabs": [
    {"id": "uuid", "title": "Tab 1", "directory": "/Users/..."}
  ]
}

new-tab

Create a new tab.

{"command": "new-tab"}

select-tab

Switch to a specific tab.

{"command": "select-tab", "id": "tab-uuid"}

current-tab

Get the currently active tab.

{"command": "current-tab"}

close-tab

Close a specific tab.

{"command": "close-tab", "id": "tab-uuid"}

Split Management

new-split

Create a new split pane.

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

Direction options: left, right, up, down

list-panels

List all panes in the current tab.

{"command": "list-panels"}

focus-panel

Focus a specific pane.

{"command": "focus-panel", "id": "panel-uuid"}

Input Control

send

Send text input to a terminal.

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

send-key

Send a key press.

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

Key options: enter, tab, escape, backspace, delete, up, down, left, right

send-panel

Send text to a specific panel.

{"command": "send-panel", "id": "panel-uuid", "text": "ls -la\n"}

send-key-panel

Send a key press to a specific panel.

{"command": "send-key-panel", "id": "panel-uuid", "key": "enter"}

Notifications

notify

Send a notification.

{
  "command": "notify",
  "title": "Build Complete",
  "subtitle": "Project X",
  "body": "Build finished successfully"
}

list-notifications

List all notifications.

{"command": "list-notifications"}

clear-notifications

Clear all notifications.

{"command": "clear-notifications"}

App Control

ping

Check if the socket is responsive.

{"command": "ping"}

Response:

{"success": true, "pong": true}

set-app-focus

Simulate app focus/unfocus (for testing).

{"command": "set-app-focus", "focused": true}

Example: Python Client

import socket
import json
 
def send_command(cmd):
    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
    sock.connect('/tmp/cmuxterm.sock')
    sock.send(json.dumps(cmd).encode() + b'\n')
    response = sock.recv(4096).decode()
    sock.close()
    return json.loads(response)
 
# List tabs
tabs = send_command({"command": "list-tabs"})
print(tabs)
 
# Send notification
send_command({
    "command": "notify",
    "title": "Hello",
    "body": "From Python!"
})

Example: Shell Script

#!/bin/bash
 
# Function to send commands
cmux_cmd() {
    echo "$1" | nc -U /tmp/cmuxterm.sock
}
 
# List tabs
cmux_cmd '{"command": "list-tabs"}'
 
# Send notification
cmux_cmd '{"command": "notify", "title": "Done", "body": "Task complete"}'

Socket API

On this page