claude-code-history-files-finder
- Repo stars 1,187
- Forks 185
- Author updated Jun 14, 2026, 10:01 AM
- Author repo claude-code-skills
- Domain
- Other
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @daymade · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: claude-code-history-files-finder
description: Finds and recovers content from Claude Code session history files. This skill should be used whe…
category: other
runtime: no special runtime
---
# claude-code-history-files-finder output preview
## PART A: Task fit
- Use case: Finds and recovers content from Claude Code session history files. This skill should be used when searching for deleted files, tracking changes across sessions, analyzing conversation history, or recovering code from previous Claude interactions. Triggers include mentions of "session history", "recover deleted", "find in history", "previous conversation", or ".claude/projects"..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Capabilities / Session File Locations / Core Operations” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Finds and recovers content from Claude Code session history files. This skill should be used when searching for deleted files, tracking changes across sessions, analyzing conversation history, or recovering code from previous Claude interactions. Triggers include mentions of "session history", "recover deleted", "find in history", "previous conversation", or ".claude/projects".”.
- **02** When the source has headings, the agent prioritizes “Capabilities / Session File Locations / Core Operations” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source mentions slash commands such as `/path`, `/daymade-claude-code`; use them first when your agent supports command triggers.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files.
Start with a small task and check whether the result follows “Capabilities / Session File Locations / Core Operations”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: claude-code-history-files-finder
description: Finds and recovers content from Claude Code session history files. This skill should be used whe…
category: other
source: daymade/claude-code-skills
---
# claude-code-history-files-finder
## When to use
- Finds and recovers content from Claude Code session history files. This skill should be used when searching for delete…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Capabilities / Session File Locations / Core Operations” and keep inference separate from source facts.
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "claude-code-history-files-finder" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Capabilities / Session File Locations / Core Operations
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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-editsflag 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
Decide Fit First
Design Intent
How To Use It
Boundaries And Review