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/, preserving the original directory structure.
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:
python3 scripts/recover_content.py session.jsonl -o ./output/
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:
find ./recovered_content/ -type f
cat ./recovered_content/recovery_report.txt
head -20 ./recovered_content/src/components/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
ls ~/.claude/projects/ | grep -i "project-name"
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:
sed -i '' 's|~/|<home>/|g' file.js
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.
Next Step: Resume Interrupted Work
After finding relevant session history, suggest continuing the work:
Found [N] relevant sessions with recoverable context.
Options:
A) Resume work — run /continue-claude-work to pick up where you left off (Recommended)
B) Just show me the content — I'll decide what to do with it
