Recover Sessions (cmux)

Overview

Bulk recover Claude Code sessions after crash or power loss into cmux workspaces. cmux variant of recover-sessions — replaces tmux backend with cmux workspace/split API.

Core principle: Claude Code conversations are safely persisted to disk as .jsonl files. Recovery = find saved sessions and open them in cmux workspaces.

When to Use

• After a Bun segfault crash that killed a Claude Code session
• After a Mac power loss when all cmux workspaces are gone
• After reboot when previous work sessions need to be restored
• Triggers: "recover cmux", "cmux session recovery", "cmux restore sessions"

Prerequisites

• cmux-recover-sessions script in skills/cmux-recover-sessions/cmux-recover-sessions (symlinked to ~/.local/bin/)
• cmux running (cmux ping should succeed) — not required for --plain and --list modes

Process

Step 1: Verify Script Installation

which cmux-recover-sessions || echo "NOT INSTALLED"

If missing, create symlink:

ln -sf ~/projects/my-skills/skills/cmux-recover-sessions/cmux-recover-sessions ~/.local/bin/cmux-recover-sessions

Also verify cmux is running:

cmux ping

Step 2: Interview — Recovery Scope

Ask the user via AskUserQuestion:

Q1: When did the crash happen?

When did the crash occur?
1. Today (recover sessions from yesterday)
2. Yesterday
3. Last Friday (weekend crash)
4. Custom date range

• Option 1 → --from <yesterday> --to <yesterday>
• Option 2 → --from <2 days ago> --to <yesterday>
• Option 3 → --from <last Monday> --to <last Friday>
• Option 4 → Ask follow-up for start/end dates (MM-DD or YYYY-MM-DD)

Step 3: Scan and Present Results

Run the scan with determined date range:

cmux-recover-sessions --list --from <start> --to <end>

Present the results to the user. If 0 sessions found, suggest widening the range.

Step 4: Interview — Session Selection

Ask the user via AskUserQuestion:

Q2: Which sessions to recover?

Found N sessions. How to filter?
1. All (recover everything)
2. Date filter (narrow to specific day)
3. Implementation/dev sessions only
4. Large sessions only (>1M)
5. Let me pick by number

Step 5: Interview — Layout

Ask the user via AskUserQuestion:

Q3: How should sessions be arranged in cmux?

How should sessions be opened?
1. Tabs — 1 workspace per session (default, recommended)
2. Split 1x2 — 2 sessions per workspace (top/bottom)
3. Split 2x1 — 2 sessions per workspace (left/right)
4. Split 2x2 — 4 sessions per workspace (grid)
5. Custom split (enter CxR)
6. Plain — output resume commands only (no workspace creation)

Show calculated workspace count: "N sessions ÷ P panes = W workspaces"

Step 6: Final Confirmation

Present the recovery plan summary and ask for explicit approval before executing:

═══════════════════════════════════════════════
 Recovery Plan (cmux)
═══════════════════════════════════════════════

 Date range:  03-23 ~ 03-25
 Sessions:    12 (filtered from 50 total)
 Layout:      tabs (1 session per workspace)
 Workspaces:  12

 Command to execute:
   cmux-recover-sessions --from 03-23 --to 03-25 --tabs

═══════════════════════════════════════════════

Proceed with recovery?
1. Yes, execute
2. Change settings
3. Cancel

Step 7: Execute Recovery

Run the approved command:

cmux-recover-sessions --from <start> --to <end> [--tabs|--split CxR|--plain]

Step 8: Verify and Guide

After execution, verify workspaces were created:

cmux list-workspaces

Show navigation instructions:

cmux workspaces are now open. Navigate with:
  Cmd+1-9         jump to workspace by number
  Cmd+Shift+]     next workspace
  Cmd+Shift+[     previous workspace

Script Reference

CLI Options

Architecture

cmux uses workspaces as the primary unit. Each workspace is a tab.

Tabs mode (default):

cmux window
  ├─ workspace 1 (tab): claude --resume session-1
  ├─ workspace 2 (tab): claude --resume session-2
  ├─ workspace 3 (tab): claude --resume session-3
  └─ workspace 4 (tab): claude --resume session-4

Plain mode:

$ cmux-recover-sessions --from 03-25 --plain

# Session 1: 하이브 좀비락 확인
cd "/Users/.../laplace-dev-hub"
claude --resume abc123

# Session 2: code-review for ...
cd "/Users/.../laplace-dev-hub"
claude --resume def456

Split mode (e.g., 1x2):

cmux window
  ├─ workspace 1: ┌─────────────┐
  │               │  session-1   │
  │               ├─────────────┤
  │               │  session-2   │
  │               └─────────────┘
  └─ workspace 2: ┌─────────────┐
                   │  session-3   │
                   ├─────────────┤
                   │  session-4   │
                   └─────────────┘

Filtering Pipeline

Same as recover-sessions — automatically excludes:

Multi Config Home Support

Scans all ~/.claude*/projects/ directories automatically. For non-default config homes (e.g., ~/.claude-5x), the resume command uses CLAUDE_CONFIG_DIR.

Prevention: Session Naming

Prevention beats recovery. Always name sessions at startup:

claude --name "hub-700-feat-xyz"

Named sessions recover instantly: claude --resume "hub-700" (fuzzy match).

Troubleshooting

Integration

Workflow position: System recovery (runs before any other skill)

[Crash / Reboot] → [cmux-recover-sessions] → [Resume daily work]