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/
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).
- 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.
- 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/
- 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.