fernandezbaptiste/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:

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:

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:

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

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

Filtering by keywords:

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

Recovers only files matching any keyword in their path.

Custom output directory:

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

4. Analyze Session Statistics

Get detailed session metrics:

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:

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

# 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

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

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