cmux

cmux

Overview

cmux is a native macOS terminal built on Ghostty with a programmable Unix socket API. This skill covers all local control: workspace and surface management, sending input, notifications, and sidebar status.

Purpose: Automate cmux workspaces, panes, and UI from within a running cmux session or any local process.

Quick Detection

# Am I inside cmux?
[ -n "$CMUX_WORKSPACE_ID" ] && echo "inside cmux" || echo "not in cmux"

# Is cmux running?
[ -S /tmp/cmux.sock ] && echo "cmux socket live"

Socket API

Connection

# Default socket (release build)
/tmp/cmux.sock

# Debug build
/tmp/cmux-debug.sock

# Override via env var
export CMUX_SOCKET_PATH=/tmp/cmux.sock

Request format — newline-terminated JSON:

echo '{"id":"req-1","method":"workspace.list","params":{}}' | nc -U /tmp/cmux.sock

Response format:

{"id":"req-1","ok":true,"result":{...}}

Helper function (paste into shell or script)

cmux_call() {
  local method=$1 params=${2:-{}}
  echo "{\"id\":\"$$\",\"method\":\"$method\",\"params\":$params}" | nc -U "${CMUX_SOCKET_PATH:-/tmp/cmux.sock}"
}

Socket Methods

System

# Ping
cmux_call system.ping

# What capabilities does this cmux version have?
cmux_call system.capabilities

# Identify current window/workspace/surface context
cmux_call system.identify

Workspace

# List all workspaces
cmux_call workspace.list

# Create new workspace
cmux_call workspace.create

# Switch to workspace
cmux_call workspace.select '{"workspace_id":"<id>"}'

# Get active workspace
cmux_call workspace.current

# Close a workspace
cmux_call workspace.close '{"workspace_id":"<id>"}'

Spawning an Agent in a New Pane (MANDATORY PATTERN)

When delegating a task to another Claude agent via cmux:

1. Split a new pane in the CURRENT workspace (never create a new workspace)
2. Check if a shell is ready — read_text to confirm prompt is showing
3. Start Claude using ccc — never use claude --print or claude directly
4. Send the task — two-step: send_text (no \n) then send_key enter
5. Tell the agent to report back to THIS terminal — instruct it to send a desktop notification AND send a message back to the calling surface via the cmux socket, so the parent Claude session gets notified