claudetools/.claude/commands/recover.md at eed3ece2c7a30d7eb531c8fea6533d2f2cbdb234

Files

Mike Swanson eed3ece2c7 feat: session recovery toolset (orphan detector + /recover)

Reconstructs session logs from Claude Code transcripts when a session
crashes or is closed before /save. Two entry points:

- /recover <uuid|latest> : manual, Claude-reviewed reconstruction
- detect_orphaned_sessions.py : scheduled scan that auto-builds logs for
  substantive, unsaved, not-yet-recovered transcripts (banner-marked
  RECOVERED-UNVERIFIED), commits them, and posts a #bot-alerts FYI.

recover_session.py is the shared engine: Python extracts the verbatim
command/config/reference timeline; Ollama drafts prose-only narrative.
Machine-local ledger (.claude/state/) prevents reprocessing. Reviewed:
git add scoped to own files, ledger written only after successful push,
per-uuid idempotency, --max cap for unattended runs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-01 18:33:07 -07:00

4.4 KiB

Raw Blame History

Reconstruct a session log from a Claude Code transcript when a session crashed or was closed before /save.

Claude Code writes every session live to a transcript JSONL under ~/.claude/projects/<slug>/<uuid>.jsonl. /recover distills one of those transcripts back into a normal session log in the .claude/commands/save.md format. This is the manual, reviewed path; the background detector (detect_orphaned_sessions.py) handles unattended auto-recovery.

Usage

Invocation	Action
`/recover <uuid>`	Reconstruct the session with that transcript uuid
`/recover latest`	Reconstruct the newest transcript by mtime
`/recover --list`	Show candidate orphans (runs the detector `--dry-run`)

Flow: `/recover --list`

Run the detector in scan-only mode and present the table to the user:

py .claude/scripts/detect_orphaned_sessions.py --dry-run

The table shows every past-idle, not-yet-processed transcript with its uuid, mtime, substantive/saved/orphan verdicts, classified scope, and the path a recovery would write to. Point the user at the rows where orphan is YES — those are unsaved substantive sessions. Nothing is written.

Flow: `/recover <uuid>` or `/recover latest`

This is a reviewed recovery. Claude is the editor, not a passive writer.

Generate the draft (prints to stdout, writes nothing):
```
py .claude/scripts/recover_session.py --uuid <uuid> --print
```
(or --latest). The draft contains:
- Ollama-drafted prose: Session Summary, Key Decisions, Problems Encountered, Pending / Incomplete Tasks.
- Python-extracted verbatim evidence: Configuration Changes, Commands & Outputs, Reference Information, Infrastructure & Servers, Credentials & Secrets.
- A [RECOVERED -- UNVERIFIED] banner and the canonical User block (from whoami-block.sh).
Review the draft. This is the point of the manual path:
- Verify the Commands / Config / Reference appendix matches what actually happened and what the user intended. These are machine-extracted verbatim — confirm they are complete and not misleading.
- Correct the scope and slug: the classifier is conservative and may land on general (or the wrong project/client) when work spanned several areas. Fix the target session-logs/ directory accordingly.
- Tighten the topic in the filename and the title.
- Correct or rewrite the Ollama prose where it is imprecise. If Ollama was unreachable, write the prose sections yourself from the verbatim evidence.
Write the final log. Once verified, write the corrected markdown to the correct session-logs/ path (client -> clients/<slug>/session-logs/, project -> projects/<project>/session-logs/, general -> root session-logs/), using the transcript's first-timestamp date: YYYY-MM-DD-recovered-<topic>.md. Drop the UNVERIFIED banner — by writing it yourself you have verified it.
Sync:
```
bash .claude/scripts/sync.sh
```
Unseeded wiki check. If the scope is a client or project with no wiki/<type>/<slug>.md article yet, suggest:
```
[INFO] No wiki article for '<slug>' yet. Run /wiki-compile <type>:<slug> to seed it.
```

Difference from the automatic detector

	`/recover` (this command)	`detect_orphaned_sessions.py` (background)
Trigger	Manual, on demand	Scheduled task (every few hours + at logon)
Review	Claude reviews and corrects before writing	None — auto-writes unreviewed
Banner	Removed once verified	Kept (`[RECOVERED -- UNVERIFIED]`) until a human reviews
Scope/topic	Corrected by Claude	Whatever the classifier decided
Output	Final, clean session log	Banner-marked draft committed for later review

Use /recover when you know a specific session was lost and want a clean log. Let the detector catch the ones you forget.

Notes

--auto and --json modes on recover_session.py exist for the detector and for scripting; /recover uses --print so Claude always reviews before anything lands on disk.
The prose is Ollama-drafted from the transcript; the Commands/Config/Reference sections are extracted verbatim by Python. Never trust the prose for exact commands, IPs, credentials, paths, SHAs, or ticket IDs — read those from the verbatim sections.
Transcripts are per-machine. You can only recover sessions that ran on the machine you are on.

4.4 KiB Raw Blame History