f36525f5f1
- Add Fumadocs-based docs site (docs-site/) - Document all features: tabs, notifications, splits, socket API, CLI - Add Claude Code hooks guide with cmuxterm detection - Update README with native macOS emphasis and brew install - Add homebrew-cmuxterm to .gitignore (has its own repo)
263 lines
4 KiB
Text
263 lines
4 KiB
Text
---
|
|
title: Socket API
|
|
description: Unix socket API for programmatic control of cmuxterm
|
|
---
|
|
|
|
# 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 |
|
|
|
|
<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/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
|
|
|
|
```bash
|
|
#!/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"}'
|
|
```
|