claude-file-recovery is a powerful tool designed for recovering files created and modified by Claude Code, leveraging JSONL session transcripts to effectively reconstruct lost files across various sessions. This project addresses the challenge of file management within Claude’s logging system by parsing detailed logs stored in ~/.claude/projects/, allowing users to retrieve lost information seamlessly.

Key Features

• Interactive TUI: Navigate efficiently with a terminal user interface that supports fuzzy search and utilizes vim-inspired key bindings (e.g., j/k for navigation, / for search).
• Point-in-Time Recovery: Recover files from any historical snapshot, enabling access to previous versions and facilitating robust file management.
• Colored Diff View: Visualize file changes over time through an enhanced diff view that supports various display modes (unified, full-context, and raw).
• Batch Extraction: Select multiple files for extraction in one go, saving time and effort in file recovery.
• Fast Scanning: Benefit from fast and parallel parsing of session transcripts, significantly speeding up recovery by pre-filtering unnecessary lines (approximately 77% skipped).
• Symlink Deduplication: Automatically detect symlinked paths and merge them into standardized entries to eliminate redundancy.
• Smart-Case Search: Conduct case-sensitive searches where applicable, making query results highly relevant.

Quick Usage Examples

To get started with the claude-file-recovery tool, you can launch the interactive TUI with:

claude-file-recovery

Subsequently, users can:

• List all recoverable files:

  claude-file-recovery list-files
  

• Filter by file patterns:

  claude-file-recovery list-files --filter '*.py'
  

• Extract specific files to disk:

  claude-file-recovery extract-files --output ./recovered --filter '*.py'
  

How It Works

The recovery process involves:

1. Scanning: All JSONL session files are discovered and parsed in parallel while skipping irrelevant lines for speed.
2. Correlating: Connections are made between tool usage and resulting file content through unique identifiers.
3. Reconstructing: Operations are replayed chronologically, reconstructing files to mirror their past states.
4. Presenting: The TUI facilitates browsing, searching, and diffing of recovered files, simplifying the management of user data.

Contributions to enhance the tool are welcome, and users are encouraged to report issues or submit pull requests for improvements.