cmux-backup

cmux-backup

Snapshot all cmux workspaces + surfaces + per-workspace CWD/git state to ~/.cmux-backups/<timestamp>.json via the cmux Unix socket API.

Invoke

/cmux-backup

Or manually:

~/.claude/scripts/cmux-backup.sh

What it captures

Field	Source
workspace id, title, index, selected	workspace.list JSON API
workspace current_directory	workspace.list .current_directory
workspace cwd (shell-reported)	sidebar_state --tab=<ws_uuid> → cwd=
workspace focused_cwd	sidebar_state → focused_cwd=
workspace git_branch	sidebar_state → git_branch=
workspace PR info	sidebar_state → pr=, pr_label=
surface id, title, type, pane_id	surface.list JSON API

Output format

{
  "timestamp": "2026-05-18T12:34:56",
  "socket": "/Users/.../cmux.sock",
  "workspace_count": 26,
  "workspaces": [
    {
      "id": "8DAE7F5B-...",
      "title": "worktree_level_choices",
      "index": 0,
      "selected": false,
      "current_directory": "$HOME",
      "cwd": "$HOME/projects/worktree_level_choices",
      "focused_cwd": "$HOME/projects/worktree_level_choices",
      "git_branch": "feat/level-choices",
      "pr": "123",
      "surfaces": [
        {
          "id": "07A1ECD6-...",
          "title": "worktree_level_choices",
          "type": "terminal",
          "pane_id": "6FECF31A-..."
        }
      ]
    }
  ]
}

Protocol used

SOCK="$CMUX_SOCKET"  # or ~/Library/Application Support/cmux/cmux.sock

# All workspaces
printf '{"method":"workspace.list","params":{}}\n' | nc -U "$SOCK"

# Surfaces per workspace
printf '{"method":"surface.list","params":{"workspace_id":"<uuid>"}}\n' | nc -U "$SOCK"

# CWD + git state per workspace
printf "sidebar_state --tab=<workspace_uuid>\n" | nc -U "$SOCK"

Dev build sockets

# Find socket for a specific dev build:
cat ~/Library/Application\ Support/cmux/dev-may-18-last-socket-path
lsof -p $(pgrep -f "cmux DEV may-18") | grep -E "\.sock"

# Use CLI with dev build socket:
CMUX_SOCKET_PATH=/tmp/cmux-debug-may-18.sock cmux list-workspaces
CMUX_SOCKET_PATH=/tmp/cmux-debug-may-18.sock cmux tree

Companion restore skill

~/.claude/scripts/cmux-restore.sh [--backup <file>] [--dry-run] [--list]

• Skips workspaces already present by title
• Creates missing ones with workspace.create + surface.send_text cd
• Headless — never calls select_workspace

Rules

1. Never call select_workspace — read-only snapshot only.
2. Use $CMUX_SOCKET env var first; fall back to ~/Library/Application Support/cmux/cmux.sock.
3. Write backup to ~/.cmux-backups/cmux-backup-<timestamp>.json.
4. Print a summary table to stdout (workspace index, title, cwd, git branch).