claude-code-history-files-finder_skill

Overview

This skill finds and recovers content from Claude Code session history files stored under ~/.claude/projects/. It helps locate deleted files, inspect past code, and reconstruct file contents written during previous Claude sessions. Use it to audit changes, recover lost work, or trace how code evolved across conversations.

How this skill works

The tool scans normalized project directories for session JSONL files and parses each record for Write, Edit, and Read tool calls. It extracts final written file contents, aggregates metadata (timestamps, sizes, tool usage), and optionally filters by keywords or session IDs. Recovery saves deduplicated files to a chosen output directory and generates a recovery report summarizing operations.

When to use it

• You suspect a file was created or overwritten in a past Claude session and want to restore it.
• You need to search conversation history for specific code snippets, error messages, or function names.
• You want to track file changes or tool usage across sessions for auditing or debugging.
• You must recover deleted or lost files after accidental removal from the workspace.
• You need session-level metrics (message counts, tool breakdowns) for analysis.

Best practices

• Run searches against the normalized project path under ~/.claude/projects/ to ensure complete coverage.
• Use distinctive keywords (file names, unique function names, error text) to narrow results.
• Specify an explicit output directory with -o and organize recovered files by feature or date.
• Verify recovered files by reading the recovery_report.txt and spot-checking critical files.
• Sanitize recovered content before sharing to remove absolute paths, API keys, or credentials.

Example use cases

• Recover the last written version of a source file after it was accidentally deleted locally.
• Find which session introduced a breaking change by searching for a failing error message across sessions.
• Export all Write tool outputs from a session to reproduce a previous build environment.
• Compare file operation counts and tool usage between two sessions to understand workflow differences.
• Batch-recover files related to a specific feature by filtering with feature-specific keywords.