Back Original

Show HN: Claude-File-Recovery, recover files from your ~/.claude sessions

PyPI version Python versions License: MIT

Recover files created and modified by Claude Code from its JSONL session transcripts — even if you lost track of them across sessions.

Claude Code stores a full log of every tool call in ~/.claude/projects/. This tool parses those transcripts, replays Write, Edit, and Read operations in order, and reconstructs the files so you can browse, search, and extract them.

claude-file-recovery TUI demo

  • Interactive TUI with fuzzy search and vim keybindings (j/k/g/G, / to search)
  • Point-in-time recovery — reconstruct files at any historical snapshot, not just the latest
  • Colored diff view showing how files changed over time (unified, full-context, and raw modes)
  • Batch extraction — select multiple files and extract them all at once
  • Fast scanning — parallel session parsing with orjson and fast-reject byte checks that skip ~77% of lines before parsing
  • Symlink deduplication — detects aliased paths and merges them into canonical entries
  • Smart-case search — case-sensitive only when your query contains uppercase (like ripgrep)
# Recommended
uv tool install claude-file-recovery

# Or with pipx
pipx install claude-file-recovery

# Or with pip
pip install claude-file-recovery

Requires Python 3.10+.

# Launch the interactive TUI (default command)
claude-file-recovery

# List all recoverable files
claude-file-recovery list-files

# Filter by pattern
claude-file-recovery list-files --filter '*.py'

# Export as CSV
claude-file-recovery list-files --filter '*.ts' --csv

# Extract files to disk
claude-file-recovery extract-files --output ./recovered --filter '*.py'

# Recover files as they were before a certain time
claude-file-recovery list-files --before '2025-02-20 14:00'

# Point to a different Claude data directory
claude-file-recovery --claude-dir /path/to/claude-backup

  1. Scan — Discovers all JSONL session files under ~/.claude/projects/ and parses them in parallel using a thread pool. A fast-reject byte check skips progress and history-snapshot lines (~77% of all lines) before touching the JSON parser.

  2. Correlate — Links tool-use requests in assistant messages to their results in user messages via tool_use_id. This is how file content (which only appears in results, not requests) gets attached to each operation.

  3. Reconstruct — Replays operations in chronological order per file path. Write ops set content, Edit ops apply string replacements, and Read ops capture snapshots. The --before flag uses binary search to cut off at any point in time.

  4. Present — The TUI lets you browse all recovered files, search with fuzzy matching, view colored diffs between snapshots, and batch-extract to disk.

Key Action
j / k Move up/down
g / G Jump to top/bottom
/ Search
Ctrl+R Cycle search mode (fuzzy / glob / regex)
x or Space Toggle file selection
Enter View file detail + diffs
d Cycle diff mode (unified / full-context / raw)
Ctrl+E Extract selected files
q Back / quit

claude-file-recovery runs entirely on your local machine.

What it reads:

  • JSONL session files in ~/.claude/projects/ (or the directory you specify via --claude-dir)
  • File-history snapshots in ~/.claude/file-history/

What it writes (only when you explicitly ask):

  • Extracted files to a directory you specify via --output

What it does NOT do:

  • No network requests — the tool works fully offline
  • No telemetry, analytics, or usage tracking
  • No data collection of any kind
  • No modification of your Claude Code session files (read-only access)

The source code is MIT-licensed and fully open for audit.

Contributions are welcome! Feel free to open an issue or submit a pull request.

MIT — Rikkert ten Klooster