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/<encoded-project-path>/<session-id>.jsonl.

The directory name is the project's ABSOLUTE working-directory path with every / replaced by - — never the basename. For example /Users/<name>/Desktop/my-app becomes -Users-<name>-Desktop-my-app, so a bare my-app cannot match a directory directly.

Before concluding a project "has no history", reverse-look-up the encoded name — do not infer absence from a failed ls:

# search the default home AND every profile home — not just ~/.claude
ls -d ~/.claude ~/.claude-profiles/* ~/.claude-* 2>/dev/null
find ~/.claude/projects ~/.claude-profiles/*/projects ~/.claude-*/projects \
  -maxdepth 1 -iname '*<project-name>*' 2>/dev/null
# grep session content across all homes at once:
grep -rl '<keyword>' ~/.claude/projects/ ~/.claude-profiles/*/projects/ ~/.claude-*/projects/ 2>/dev/null

A ls <basename> that returns nothing means the lookup used the wrong name, NOT that history is absent. The bundled analyze_sessions.py already expands ~, resolves to an absolute path, falls back to a basename reverse-lookup, and searches every profile home — prefer passing it the path (absolute, ~, relative, or bare name all work).

Note: sessions run from Claude Desktop's cowork / built-in Claude Code mode also land here (Desktop runs a bundled CLI); only Desktop's native chat lives elsewhere (a LevelDB store, not JSONL). So "it ran inside Desktop" does not mean it is missing from ~/.claude/projects/.

Multiple config homes (profiles) — searched by default, and why it matters

~/.claude is only the default home. Anyone who runs Claude Code against third-party models through per-model profiles (each profile is its own CLAUDE_CONFIG_DIR) accumulates parallel history that never touches ~/.claude:

• ~/.claude-profiles/<name>/projects/… — one per profile (e.g. a kimi, deepseek, glm, step profile)
• ~/.claude-<name>/projects/… — occasional sibling homes
• whatever CLAUDE_CONFIG_DIR points at in the current shell

This is the #1 silent blind spot. A conversation held in a profile is completely invisible to any search that only looks at ~/.claude/projects/. Concluding "no session did X" — or worse, "this file wasn't generated by any conversation" — from a main-home-only search is a false negative: the session may be sitting in a profile home you never looked at.

analyze_sessions.py handles this for you: list and search auto-discover every home (~/.claude + all ~/.claude-profiles/* + sibling ~/.claude-*), de-duplicate sessions by id (a conversation shared across profiles is reported once), and label each result with its source profile (Profile: main / Profile: kimi / Profile: main, deepseek, …). Scope it when needed:

# default: all homes
scripts/analyze_sessions.py search /path/to/project keyword

# only ~/.claude (reproduces the old main-only behavior)
scripts/analyze_sessions.py search /path/to/project keyword --main-only

# restrict to specific home(s)
scripts/analyze_sessions.py search /path/to/project keyword --home ~/.claude-profiles/kimi

If you grep the raw JSONL by hand instead of using the script, you MUST include the profile homes — see the manual-lookup snippet below. A bare ~/.claude/projects/ grep will lie to you.

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 — check the default home AND profile homes
ls ~/.claude/projects/ ~/.claude-profiles/*/projects/ 2>/dev/null | grep -i "project-name"

# Check actual projects directories across all homes
ls -la ~/.claude/projects/ ~/.claude-profiles/*/projects/ 2>/dev/null

"Not found" is far more often a wrong-home than a truly-absent session. If analyze_sessions.py reports a match count of 0, confirm it actually searched the profile homes (its output prints Searched N home(s): main, …). A result that only says Searched 1 home(s): main means profiles were skipped (e.g. --main-only was passed) — re-run without that flag before concluding the session does not exist.

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 /daymade-claude-code: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