claude-file-recovery

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.

Features

• 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)

Installation

# 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+.

Quick Start

# 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

How It Works

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.

TUI Keybindings

| 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 |

Privacy and Data Access

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.

Contributing

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

License

MIT — Rikkert ten Klooster