What this tool does

claude-file-recovery is a Python command-line tool with an interactive TUI that extracts files from Claude Code's session history. It was created after the author accidentally deleted files through a symlink that Claude Code didn't recognize, and their backup hadn't run for a month. The tool reconstructs files by parsing JSONL session transcripts stored in ~/.claude/projects/.

Key features and functionality

The tool can recover any file that Claude Code ever read, edited, or wrote, including earlier versions of files at specific points in time. It offers:

• 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 and usage

Requires Python 3.10+. Installation options:

# Recommended
uv tool install claude-file-recovery

Or with pipx
pipx install claude-file-recovery
Or with pip
pip install claude-file-recovery

Basic commands:

# 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

The tool scans all JSONL session files under ~/.claude/projects/ and parses them in parallel using a thread pool. It correlates tool-use requests in assistant messages to their results in user messages via tool_use_id, then reconstructs files by replaying operations in chronological order per file path: Write operations set content, Edit operations apply string replacements, and Read operations capture snapshots. The --before flag uses binary search to cut off at any point in time.

TUI keybindings

• 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

This type of recovery tool is useful for developers who use Claude Code extensively and want insurance against accidental file deletion or corruption. The MIT-licensed project has 26 stars and 1 fork on GitHub as of this writing.