Cmux CLI

cmux CLI

Use the cmux CLI as the default interface. Treat every command as acting on a specific workspace, panel, or surface. Observable behavior is the anchor: state the intended target, run the command, then query the cmux state that can prove the result.

Establish Context

1. Run cmux ping. If it fails, report that cmux is unavailable or not responding. Do not install it, change socket settings, or use another terminal manager unless the user asks.
2. Run cmux identify --json to capture the focused window, workspace, panel, and surface. Use cmux current-workspace --json or cmux list-workspaces --json when the request names a workspace rather than the focused one.
3. For a non-focused target, resolve its identifier from JSON output and pass the documented scope flag: --window, --workspace, or --surface. Request --id-format both if a reference ID and UUID must be distinguished.

Say: “The observable behavior I will verify is that surface <id> receives the requested input.” Never infer the target from a previous command when a fresh query can establish it.

Execute the Requested Operation

Use one cmux command per shell call. Prefer JSON output when parsing IDs or reporting state. Read references/cli-reference.md from this skill's directory when an operation is uncommon or its exact flags are not below.

Workspace and Panels

cmux new-workspace
cmux select-workspace --workspace <workspace-id>
cmux new-split right
cmux list-panels --json
cmux focus-panel --panel <surface-id>

new-split accepts left, right, up, or down. Create a workspace or split only when the user requested that state change. Before close-workspace --workspace <workspace-id>, identify the workspace and obtain explicit user intent to close it.

Terminal Input

Send text to the explicit surface when a target is known. Send Enter separately when the text is meant to execute.

cmux send --surface <surface-id> "npm test"
cmux send-key --surface <surface-id> enter

send changes terminal input and send-key enter executes it. Do not send a command to a terminal merely to inspect state. Inspect with the cmux query commands first. send-key supports enter, tab, escape, backspace, delete, and the arrow keys.

Status, Progress, Logs, and Notifications

Use a unique, task-scoped key for status. Clear only state owned by that key. Set status, progress, or logs only when the user asked to report task state. Create a notification only on an explicit notification request.

cmux set-status task-build "running" --icon hammer --color "#ff9500" --priority 80
cmux set-progress 0.5 --label "Tests running"
cmux log --level progress --source task-build "Tests started"
cmux notify --title "Task complete" --body "Tests passed"

clear-notifications and clear-log remove shared state. Run either only on an explicit request. Use cmux sidebar-state to report the resulting status, progress, and recent operational context.

Verify and Report

The acceptance contract is a successful command followed by an independent cmux query that shows the requested result:

For terminal input, report the target and exact text or key sent. Do not claim the terminal command itself succeeded unless its own output can be observed. Report the cmux command, resolved target, and verification result. If cmux returns an error, stop the requested operation and include its error text.

Socket Boundary

Use the CLI unless the user explicitly asks for socket automation. For a socket request, read references/cli-reference.md; use only JSON requests with id, method, and params. Do not enable CMUX_SOCKET_MODE=allowAll or change CMUX_SOCKET_PATH without explicit user approval.