Design — /recover: rebuild a crashed Claude Code session from disk

Goal

Add a manually-invoked /recover skill that, when the user opens Claude in a repo whose previous session crashed (computer died, terminal closed, Claude broke mid-task) and the session ID is unknown, finds the most-recently-active prior session for that folder, reconstructs its working state from the raw on-disk transcript, and injects a budgeted digest into the current session so work continues right where it left off. It also surfaces the native claude --resume <id> command for a true thread continuation.

Why this exists (and why not the built-ins)

Claude Code already ships claude --continue/-c (resume the most recent session in the cwd) and claude --resume (interactive picker). Those are excellent — but they have two gaps /recover fills:

• They require a fresh terminal. A skill runs inside an already-started session with no usable interactive TTY. It cannot meaningfully shell out to an interactive claude --resume (the picker needs a TTY) and spawning a nested claude is nonsense — the child's restored thread can't be piped back into the parent's context. So /recover reads the transcript itself and injects a digest into the current session, and merely prints claude --resume <id> as a suggestion the user runs from a real terminal.
• They replay the full thread. /recover produces a budgeted, noise-stripped digest (what was the goal, what was the plan, what was in flight) — useful when you want orientation fast, or the full transcript is too large, or you just want to keep going in the session you already have open.

The neighboring jacked skills stay in their lanes. The dividing line is the source of truth and the precondition:

Architecture

Three components with clean boundaries. The hard parts (JSONL parsing, repo-path mapping, noise-stripping, summary extraction) already exist in transcript.py and config.py — both verified Qdrant-free (stdlib imports only). The new logic is a thin, unit-testable layer plus a Click subcommand plus a Markdown skill.

• jacked/recover.py — pure logic. Resolves the project dir for the cwd, ranks candidate sessions (excluding the live one), and builds a budgeted digest. Imports transcript.py + config.py only.
• jacked recover — a Click subcommand in cli.py (matches the existing Click pattern; not _require_search-gated). Two phases so we confirm before injecting: --json (rank candidates, cheap metadata) and --session <id> --digest (the actual working-state digest).
• jacked/data/skills/recover/SKILL.md — thin orchestrator. Runs the CLI, presents the auto-pick, confirms, injects the digest, and re-anchors. Installs to ~/.claude/skills/recover/SKILL.md automatically via the existing jacked install glob.

flowchart TD
    A[User runs /recover] --> B["jacked recover --json --exclude $CLAUDE_CODE_SESSION_ID"]
    B --> C[recover.py: resolve project dir for cwd]
    C --> D[Rank candidates by last timestamped line; exclude live session]
    D --> E{Any candidates?}
    E -->|no| F[Tell user: no prior session for this folder — stop]
    E -->|yes| G[Skill shows auto-pick: title · last prompt · when · branch + alternates]
    G --> H{User confirms pick?}
    H -->|wrong one| I[User names an alternate]
    I --> J
    H -->|yes| J["jacked recover --session ID --digest"]
    J --> K[recover.py build_digest: budgeted, noise-stripped, TodoWrite, incomplete-turn flag]
    K --> L[Digest printed into current context = injection + print 'claude --resume ID']
    L --> M[Re-anchor: you were doing X, next step was Y — ready to continue]
  

flowchart TD
    A[User runs /recover] --> B["jacked recover --json --exclude $CLAUDE_CODE_SESSION_ID"]
    B --> C[recover.py: resolve project dir for cwd]
    C --> D[Rank candidates by last timestamped line; exclude live session]
    D --> E{Any candidates?}
    E -->|no| F[Tell user: no prior session for this folder — stop]
    E -->|yes| G[Skill shows auto-pick: title, last prompt, when, branch + alternates]
    G --> H{User confirms pick?}
    H -->|wrong one| I[User names an alternate]
    I --> J
    H -->|yes| J["jacked recover --session ID --digest"]
    J --> K[recover.py build_digest: budgeted, noise-stripped, TodoWrite, incomplete-turn flag]
    K --> L[Digest printed into current context = injection + print 'claude --resume ID']
    L --> M[Re-anchor: you were doing X, next step was Y — ready to continue]
  

recover.py public functions

Session resolution & live-session exclusion

Two subtleties, both verified empirically against real files on this machine, drive correctness here.

The path slug eats dots

A cwd maps to a projects folder by replacing both / and . with -. /Users/jack.neil/Github/claude-jacked → -Users-jack-neil-Github-claude-jacked. A naïve /-only slug misses it, and a stale dot-preserving folder from an older build also exists. Resolution therefore never trusts the slug alone — it verifies (or discovers) the folder by reading the cwd field stored inside the transcripts.

Excluding the currently-running session

Robust exclusion strategy, in order:

1. Skill passes --exclude "$CLAUDE_CODE_SESSION_ID" at the shell level. This captures the value where it's known to be set, independent of the Python subprocess environment — the primary mechanism.
2. CLI fallback: if --exclude is empty, read CLAUDE_CODE_SESSION_ID, then CLAUDE_SESSION_ID, from the environment.
3. Belt-and-suspenders heuristic: also drop any candidate whose last timestamped line is within ~60s of now and whose tail looks live (ends in fresh assistant/system traffic rather than the untimestamped last-prompt/ai-title/mode/permission-mode tail a finished session leaves). This guards the rare case where the env var is unavailable.

The digest: what gets recovered

There is no summary line type in the transcript format — recap state lives in lightweight metadata lines. build_digest walks the chosen transcript (skipping isSidechain subagent branches) and assembles, in priority order:

• Session title — the ai-title line (one-line "what this was about").
• Last instruction — the last-prompt line (lastPrompt), the fastest "what was I doing" signal.
• Recent real asks — the last few user messages with isMeta:true and <command-name>… wrappers stripped.
• Last assistant plan/answer — trailing assistant text blocks (tool-output noise removed).
• Todo state — the latest TodoWrite tool_use block's input.todos (content + status: in-progress / pending / completed), if any. Not every session has one.
• Recent tool actions — trailing tool_use names + key inputs (Bash commands, Edit/Write file paths) to show the last concrete operations.
• Files touched — from Edit/Write/NotebookEdit input.file_path and file-history-snapshot entries.
• git branch & modes — the last gitBranch, plus mode/permission-mode to re-establish posture.
• Incomplete-turn flag — if the tail is a tool_use with no matching tool_result, or a half-written final line, mark "last turn may be incomplete — work was in progress on X" rather than presenting it as finished.

CLI surface

# Phase 1 — rank candidates (cheap metadata, machine-readable)
jacked recover --json [--cwd PATH] [--exclude SESSION_ID] [--limit N]

# Phase 2 — build the digest for the confirmed session (the injection payload)
jacked recover --session <id> --digest [--budget N] [--cwd PATH]

The /recover skill flow

A thin SKILL.md (frontmatter: name: recover + a trigger-tight description anchored on "session/computer crashed mid-work," "didn't run /checkpoint," "session ID unknown," "rebuild this folder's last session from the transcript" — and explicitly not for transient API errors, deliberately-saved state, or topic search across old projects). The body:

1. Run jacked recover --json --exclude "$CLAUDE_CODE_SESSION_ID".
2. No candidates → tell the user no prior session was found for this folder (fresh repo / wrong folder / nothing crashed here) and stop. Don't fabricate.
3. Present the auto-pick — title · last prompt · when · branch — plus the alternates list. Confirm before injecting.
4. On confirm → jacked recover --session <id> --digest; that output is the injected working state. Then surface claude --resume <id> as "for a true native continuation (preserves Claude's internal state), run this in a fresh terminal."
5. Re-anchor in one or two lines: "You were doing X; the next step was Y," nodding to MEMORY.md for standing project conventions, and continue the work.
6. Wrong pick → the user names an alternate from the list → re-call with --session <alt>.

File changes

Testing

Python (TDD, pytest)

• resolve_project_dir: dot-slug folder, enumerate-and-match fallback, stale dot-preserving folder ignored, missing folder → None.
• list_candidates: excludes the live session id; ranks by last timestamped line (not mtime); ignores subagent <uuid>/ dirs; multiple-candidate ordering; tolerates a malformed/half-written final line without aborting the parse.
• build_digest: extracts ai-title/last-prompt/recent asks/last assistant text; pulls the latest TodoWrite; flags an incomplete final turn; respects --budget and emits the truncation note (no silent drop); strips tool-output noise.
• resume_command: exact string.

Skill (writing-skills RED → GREEN)

This is a technique skill, so test by application. RED: give a fresh agent "my session in this repo crashed, recover it" without the skill and document the flailing (won't know the env var to exclude, won't handle the dot-slug, may reach for Qdrant/jacked, may dump the whole transcript). GREEN: with the skill, the agent runs the two-phase CLI, confirms the pick, injects a budgeted digest, and offers claude --resume. REFACTOR: close any gaps surfaced.

Scope boundaries (YAGNI)

• No Qdrant / [search] dependency — works on a bare install, by design.
• No nested/shelled claude --resume — TTY + nested-session problems make it unworkable; we print the command for the user to run.
• No SessionStart auto-hook — a hook can't distinguish a crash from a normal boot and would nag or mis-fire. Manual /recover only, per the user's ask.
• No cross-machine / cross-repo search — that's /jacked's job. /recover is strictly "this folder's last session."
• No write-back, no transcript editing, no checkpoint artifact — recovery injects into the live context; if the user wants durability afterward they can run /checkpoint.
• No automatic injection without confirmation — wrong-session is the headline risk; the user confirms the pick first.

Failure modes

Open questions

• Default --budget units & value — characters vs lines, and the exact cap. Leaning lines (~3000) to mirror /checkpoint; finalize during implementation against a real large transcript.
• Should phase-1 --json ever auto-skip confirmation when there is exactly one candidate and it's unambiguous? Current spec: always confirm (cheap, and wrong-session is the headline risk). Revisit only if it feels heavy in practice.

Generated with the jacked HTML artifact template.