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:

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 directory structure (files preserved in subdirectories)

find ./recovered_content/ -type f

Read recovery report (shows full output paths)

cat ./recovered_content/recovery_report.txt

Spot-check content (use actual path from report)

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

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|~/|<home>/|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.

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