ryoppippi/cmux-debug

cmux Debug

Use this skill when the user wants to debug or verify CLI output inside a cmux pane or surface instead of relying only on non-interactive stdout.

Workflow

1. Confirm cmux is reachable and the capture API exists.
2. Identify the target workspace and surface.
3. Run the command in that surface.
4. Capture visible output and scrollback.
5. 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.