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.