claude-code-history-files-finder

# Claude Code History Files Finder

Extract and recover content from Claude Code's session history files stored in `~/.claude/projects/`.

## Capabilities

- Recover deleted or lost files from previous sessions
- Search for specific code or content across conversation history
- Analyze file modifications across past sessions
- Track tool usage and file operations over time
- Find sessions containing specific keywords or topics

## Session File Locations

Session files are stored at `~/.claude/projects/<normalized-path>/<session-id>.jsonl`.

For detailed JSONL structure and extraction patterns, see `references/session_file_format.md`.

## Core Operations

### 1. List Sessions for a Project

Find all session files for a specific project:

```bash
python3 scripts/analyze_sessions.py list /path/to/project
```

Shows most recent sessions with timestamps and sizes.

Optional: `--limit N` to show only N sessions (default: 10).

### 2. Search Sessions for Keywords

Locate sessions containing specific content:

```bash
python3 scripts/analyze_sessions.py search /path/to/project keyword1 keyword2
```

Returns sessions ranked by keyword frequency with:
- Total mention count
- Per-keyword breakdown
- Session date and path

Optional: `--case-sensitive` for exact matching.

### 3. Recover Deleted Content

Extract files from session history:

```bash
python3 scripts/recover_content.py /path/to/session.jsonl
```

Extracts all Write tool calls and saves files to `./recovered_content/`.

**Filtering by keywords**:

```bash
python3 scripts/recover_content.py session.jsonl -k ModelLoading FRONTEND deleted
```

Recovers only files matching any keyword in their path.

**Custom output directory**:

```bash
python3 scripts/recover_content.py session.jsonl -o ./my_recovery/
```

### 4. Analyze Session Statistics

Get detailed session metrics:

```bash
python3 scripts/analyze_sessions.py stats /path/to/session.jsonl
```

Reports:
- Message counts (user/assistant)
- Tool usage breakdown
- File operation counts (Write/Edit/Read)

Optional: `--show-files` to list all file operations.

## Workflow Examples

For detailed workflow examples including file recovery, tracking file evolution, and batch operations, see `references/workflow_examples.md`.

## Recovery Best Practices

### Deduplication

`recover_content.py` automatically keeps only the latest version of each file. If a file was written multiple times in a session, only the final version is saved.

### Keyword Selection

Choose distinctive keywords that appear in:
- File names or paths
- Function/class names
- Unique strings in code
- Error messages or comments

### Output Organization

Create descriptive output directories:

```bash
# Bad
python3 scripts/recover_content.py session.jsonl -o ./output/

# Good
python3 scripts/recover_content.py session.jsonl -o ./recovered_deleted_docs/
python3 scripts/recover_content.py session.jsonl -o ./feature_xy_history/
```

### Verification

After recovery, always verify content:

```bash
# Check file list
ls -lh ./recovered_content/

# Read recovery report
cat ./recovered_content/recovery_report.txt

# Spot-check content
head -20 ./recovered_content/ImportantFile.jsx
```

## Limitations

### What Can Be Recovered

✅ Files written using Write tool
✅ Code shown in markdown blocks (partial extraction)
✅ File paths from Edit/Read operations

### What Cannot Be Recovered

❌ Files never written to disk (only discussed)
❌ Files deleted before session start
❌ Binary files (images, PDFs) - only paths available
❌ External tool outputs not captured in session

### File Versions

- Only captures state when Write tool was called
- Intermediate edits between Write calls are lost
- Edit operations show deltas, not full content

## Troubleshooting

### No Sessions Found

```bash
# Verify project path normalization
ls ~/.claude/projects/ | grep -i "project-name"

# Check actual projects directory
ls -la ~/.claude/projects/
```

### Empty Recovery

Possible causes:
- Files were edited (Edit tool) but never written (Write tool)
- Keywords don't match file paths in session
- Session predates file creation

Solutions:
- Try `--show-edits` flag to see Edit operations
- Broaden keyword search
- Search adjacent sessions

### Large Session Files

For sessions >100MB:
- Scripts use streaming (line-by-line processing)
- Memory usage remains constant
- Processing may take 1-2 minutes

## Security & Privacy

### Before Sharing Recovered Content

Session files may contain:
- Absolute paths with usernames
- API keys or credentials
- Company-specific information

Always sanitize before sharing:

```bash
# Remove absolute paths
sed -i '' 's|/Users/[^/]*/|/Users/username/|g' file.js

# Verify no credentials
grep -i "api_key\|password\|token" recovered_content/*
```

### Safe Storage

Recovered content inherits sensitivity from original sessions. Store securely and follow organizational policies for handling session data.