| name | cmux-debug |
| description | Guides cmux terminal debugging. Use when validating CLI visual output, responsive tables, terminal geometry, long-running commands, or pane captures. |
cmux Debug
Use this skill when the user wants to debug or verify CLI output inside a cmux pane/surface instead of relying only on non-interactive stdout.
Workflow
- Confirm cmux is reachable and the capture API exists.
- Identify the target workspace and surface.
- Run the command in that surface.
- Capture visible output and scrollback.
- For responsive terminal UI bugs, capture terminal geometry from the same surface.
Commands
Check availability:
cmux ping
cmux capabilities --json | jq '.methods'
Find targets:
cmux list-workspaces --json
cmux list-surfaces --workspace <workspace> --json
cmux list-pane-surfaces --workspace <workspace> --json
Read output:
cmux read-screen --workspace <workspace> --surface <surface> --lines 80
cmux capture-pane --workspace <workspace> --surface <surface> --scrollback --lines 120
Run a command and capture it:
cmux send --workspace <workspace> --surface <surface> "printf '\\033c'; cd <cwd>; <command>\n"
cmux capture-pane --workspace <workspace> --surface <surface> --scrollback --lines 120
Capture geometry with the command output:
cmux send --workspace <workspace> --surface <surface> "printf '\\033c'; stty size; printf 'COLUMNS=%s\n' \"\$COLUMNS\"; cd <cwd>; <command>\n"
cmux read-screen --workspace <workspace> --surface <surface> --lines 120
Use socket RPC when the CLI wrapper is not enough:
cmux rpc surface.read_text '{"workspace_id":"<workspace_uuid>","surface_id":"<surface_uuid>","scrollback":true,"lines":120}'
Checks
- Use the same surface for command execution,
stty size, $COLUMNS, and output capture.
- Prefer
capture-pane --scrollback when the command output may exceed the visible viewport.
- For table layout bugs, verify that rendered width fits the captured terminal width and that important columns such as dates and totals are not truncated.
- If
read-screen or capture-pane is unavailable, inspect cmux capabilities --json and fall back to surface.read_text via cmux rpc.
