claudetools/.claude/commands/recover.md at 2fcdc5fb1361ba42ed867c09b54d7945ac477275

Files

Mike Swanson 446a6c1b1c sync: auto-sync from GURU-5070 at 2026-06-02 20:40:54

Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-02 20:40:54

2026-06-02 20:40:58 -07:00

5.5 KiB

Raw Blame History

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

Claude Code: ~/.claude/projects/<slug>/<uuid>.jsonl
Grok: ~/.grok/sessions/<slug>/<uuid>/ (chat_history.jsonl + events + terminal/call-*.log etc.)

/recover distills the transcript back into a normal ClaudeTools session log (the format used by /save). This is the manual, reviewed path. The driver is auto-detected or can be forced.

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.

Grok sessions

Grok stores richer per-session artifacts (separate chat_history, events, per-tool terminal logs with full output, summary, etc.) under ~/.grok/sessions/<slug>/<uuid>/.

The companion script is .claude/scripts/recover_grok_session.py.

Current support (MVP):

--list, --latest, --uuid <id> work and locate the right dir using the same slug rules Grok uses.
Extracts terminal command logs (highest value verbatim evidence) + basic metadata.
--print and --auto (writes under session-logs/grok-session-....md).

Full parity with the Claude recover (conversation reconstruction + Ollama prose for Summary/Decisions + exact file-edit extraction) is planned; the two scripts can share helpers later.

In /recover flows, if the chosen orphan or explicit id lives under a Grok sessions tree, the Grok script is used automatically (future enhancement to the dispatcher in recover_session.py or a thin wrapper).

Example (manual):

py .claude/scripts/recover_grok_session.py --latest --print
py .claude/scripts/recover_grok_session.py --uuid 019e8b67-f97e-7b33-9c45-ec34b342d3eb --auto

5.5 KiB Raw Blame History