109 lines
5.5 KiB
Markdown
109 lines
5.5 KiB
Markdown
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
1. **Generate the draft** (prints to stdout, writes nothing):
|
|
|
|
```bash
|
|
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`).
|
|
|
|
2. **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.
|
|
|
|
3. **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.
|
|
|
|
4. **Sync:**
|
|
|
|
```bash
|
|
bash .claude/scripts/sync.sh
|
|
```
|
|
|
|
5. **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):
|
|
```bash
|
|
py .claude/scripts/recover_grok_session.py --latest --print
|
|
py .claude/scripts/recover_grok_session.py --uuid 019e8b67-f97e-7b33-9c45-ec34b342d3eb --auto
|
|
```
|