cmux-recover-sessions

Files (3)

• SKILL.md
• claude-recover-scan
• cmux-recover-sessions

SKILL.md (first lines)

# Recover Sessions (cmux)

## Overview

Bulk recover Claude Code sessions after crash or power loss into cmux workspaces.
The bundled `claude-recover-scan` finds the sessions on disk; `cmux-recover-sessions` reopens each one through the 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.

## The Iron Law

```
RECOVERY IS NEVER DESTRUCTIVE. LIVE WORKSPACES MUST NOT BE TOUCHED.
```

Recovery reads `.jsonl` files and re-opens them in new cmux workspaces. It must never:
- Close or replace any currently running cmux workspace
- Overwrite or delete saved conversation files
- Modify working directories — `cwd` is informational only

## 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

## Prerequisites

- `cmux-recover-sessions` script bundled at `${CLAUDE_SKILL_DIR}/cmux-recover-sessions`; no install step (`scripts/install.sh` can additionally symlink it into `~/.local/bin` for running the tool from a terminal — optional, not part of this skill's flow)
- `claude-recover-scan` (the session scanner, `python3` standard library only) bundled next to it at `${CLAUDE_SKILL_DIR}/claude-recover-scan`; the wrapper resolves it as a sibling, through symlinks
- cmux running (`cmux ping` should succeed) — not required for `--plain` and `--list` modes

## Process

### Step 1: Locate the Script

`${CLAUDE_SKILL_DIR}` is the directory holding this SKILL.md, regardless of the current working directory, so every step below addresses the bundled script by that path. Confirm it resolves:

```bash
"${CLAUDE_SKILL_DIR}/cmux-recover-sessions" --help
```

Also verify cmux is running:

```bash
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. Earlier this week
4. Custom date range
```

- Option 1 → `--from <yesterday> --to <yesterday>`
- Option 2 → `--from <2 days ago> --to <yesterday>`
- Option 3 → `--from <this Monday> --to <yesterday>`
- 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:

```bash
"${CLAUDE_SKILL_DIR}/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)
═══════════════════════════════════════════════

From devseunggwan/praxis, MIT.

More from devseunggwan/praxis