Metadata-Version: 2.4
Name: claude-file-recovery
Version: 0.2.0
Summary: Recover files created and modified by Claude Code from session transcripts
Project-URL: Homepage, https://github.com/hjtenklooster/claude-file-recovery
Project-URL: Repository, https://github.com/hjtenklooster/claude-file-recovery
Project-URL: Issues, https://github.com/hjtenklooster/claude-file-recovery/issues
Project-URL: Changelog, https://github.com/hjtenklooster/claude-file-recovery/blob/main/CHANGELOG.md
Author: Rikkert ten Klooster
License-Expression: MIT
License-File: LICENSE
Keywords: claude,claude-code,cli,jsonl,recovery,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: orjson>=3.9
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=8.0
Requires-Dist: typer>=0.9
Description-Content-Type: text/markdown

# claude-file-recovery

[![PyPI version](https://img.shields.io/pypi/v/claude-file-recovery.svg)](https://pypi.org/project/claude-file-recovery/)
[![Python versions](https://img.shields.io/pypi/pyversions/claude-file-recovery.svg)](https://pypi.org/project/claude-file-recovery/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Recover files created and modified by [Claude Code](https://docs.anthropic.com/en/docs/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](https://raw.githubusercontent.com/hjtenklooster/claude-file-recovery/main/demo/demo.gif)

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

```bash
# 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

```bash
# 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 |

## Contributing

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

## License

[MIT](LICENSE) — Rikkert ten Klooster
