QuantumBFS Claude Log Restore
Use this skill to recover useful context from Claude Code transcripts. Claude
Code stores session transcripts as local JSONL files under
~/.claude/projects/<encoded-project-path>/<session-id>.jsonl. The encoded
project path is normally the absolute path with / replaced by -; for
example /Users/foo/repo becomes -Users-foo-repo.
Official Claude Code docs say /resume, claude --resume, and /export are
the supported session interfaces. They also document that transcript files live
under ~/.claude/projects/<project>/<session-id>.jsonl and are cleaned up after
30 days by default unless configured otherwise. Checkpoint restore is done from
Claude Code itself with /rewind; local transcript recovery only reads and
summarizes the saved JSONL.
Fast path
Use the bundled script first:
python ${CLAUDE_SKILL_DIR}/scripts/claude_log_restore.py <hash-or-uuid-prefix> --project "$PWD" --handoff
Common variants:
# List recent Claude sessions for the current project.
python ${CLAUDE_SKILL_DIR}/scripts/claude_log_restore.py --project "$PWD"
# Find a session by partial UUID/hash across all Claude projects.
python ${CLAUDE_SKILL_DIR}/scripts/claude_log_restore.py 13e617 --all-projects
# Search current project's transcripts for handoff-like notes.
python ${CLAUDE_SKILL_DIR}/scripts/claude_log_restore.py --project "$PWD" --handoff --limit 20
# Search all projects for keywords.
python ${CLAUDE_SKILL_DIR}/scripts/claude_log_restore.py --all-projects -q "ringMPS" -q "next steps"
The script streams JSONL line by line, so it is safe for multi-MB transcript
files. It prints the matching transcript path, session id, approximate resume
command, and selected snippets. Add --json for machine-readable output.
Manual fallback
When the script is unavailable, do not cat large transcript files. Check sizes
and search first:
project_dir="$HOME/.claude/projects/$(pwd | sed 's|^/|-|; s|/\.\([^/]*\)|--\1|g; s|/|-|g')"
find "$project_dir" -maxdepth 2 -name '*.jsonl' -print0 | xargs -0 ls -lh
rg -n -i 'handoff|hand off|hands off|next steps|summary|blocked|todo|resume' "$project_dir"
If the user gives a hash or UUID prefix, locate the transcript by prefix:
find "$HOME/.claude/projects" -name '<prefix>*' -print
Once the session id is known, the normal resume command is:
claude --resume <session-id>
If Claude needs in-session restore of code or conversation, tell the user to use
/rewind inside that Claude session. Transcript mining can recover context and
handoff notes, but it does not rewrite Claude's checkpoint state.
Output discipline
Report recovered context with concrete paths and session IDs. Separate direct log evidence from inference. If the transcript contains large tool outputs or hook-injected instructions, summarize only the relevant user/assistant messages and avoid pasting secrets or huge outputs.