---
title: Socket API
description: Unix socket API for programmatic control of cmux
---

# Socket API

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

## Socket Location

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

You can override the path with the `CMUX_SOCKET_PATH` environment variable.

## Access Modes

cmux has three access modes, configurable in Settings:

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

<Callout type="warn">
  On shared machines, use "Notifications only" mode to prevent other users from controlling your terminals.
</Callout>

## Protocol

Commands are sent as newline-terminated JSON:

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

Responses are newline-terminated JSON:

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

## Commands Reference

### Tab Management

#### list-tabs

List all open tabs.

```json
{"command": "list-tabs"}
```

Response:

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

#### new-tab

Create a new tab.

```json
{"command": "new-tab"}
```

#### select-tab

Switch to a specific tab.

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

#### current-tab

Get the currently active tab.

```json
{"command": "current-tab"}
```

#### close-tab

Close a specific tab.

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

### Split Management

#### new-split

Create a new split pane.

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

Direction options: `left`, `right`, `up`, `down`

#### list-panels

List all panes in the current tab.

```json
{"command": "list-panels"}
```

#### focus-panel

Focus a specific pane.

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

### Input Control

#### send

Send text input to a terminal.

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

#### send-key

Send a key press.

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

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

#### send-panel

Send text to a specific panel.

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

#### send-key-panel

Send a key press to a specific panel.

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

### Notifications

#### notify

Send a notification.

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

#### list-notifications

List all notifications.

```json
{"command": "list-notifications"}
```

#### clear-notifications

Clear all notifications.

```json
{"command": "clear-notifications"}
```

### App Control

#### ping

Check if the socket is responsive.

```json
{"command": "ping"}
```

Response:

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

#### set-app-focus

Simulate app focus/unfocus (for testing).

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

## Example: Python Client

```python
import socket
import 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 tabs
tabs = send_command({"command": "list-tabs"})
print(tabs)

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

## Example: Shell Script

```bash
#!/bin/bash

# Function to send commands
cmux_cmd() {
    echo "$1" | nc -U /tmp/cmux.sock
}

# List tabs
cmux_cmd '{"command": "list-tabs"}'

# Send notification
cmux_cmd '{"command": "notify", "title": "Done", "body": "Task complete"}'
```