Claude Code History Files Finder
Search Claude Code session JSONL history and recover deleted or lost content from past agent sessions.
Overview
Claude Code History Files Finder is an agent skill most often used in Build (also Operate) that locates and recovers content from local Claude Code session history JSONL files using bundled Python scripts.
Install
npx skills add https://github.com/daymade/claude-code-skills --skill claude-code-history-files-finderWhat is this skill?
- Marketplace skill with SKILL.md (~314 lines), two scripts, and session JSONL format reference
- analyze_sessions.py for session search and analysis across history files
- recover_content.py for extracting and recovering content from past sessions
- references/session_file_format.md documents JSONL session structure
- .security-scan-passed marker in marketplace packaging (verify current audit on Prism)
- 2 production scripts: analyze_sessions.py and recover_content.py
- SKILL.md documented at ~314 lines in integration summary
- Marketplace version noted as 1.12.0 with 19 skills in bundle metadata
Adoption & trust: 534 installs on skills.sh; 1.2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You lost code or instructions from a Claude Code session and cannot find them in the editor or git, but session history may still exist on disk.
Who is it for?
Claude Code users on a local dev machine who need forensic search and recovery in session history without a third-party backup product.
Skip if: Teams without Claude Code local history, cloud-only agent setups, or recovery needs that require remote server session logs.
When should I use this skill?
You need to find, analyze, or recover content from Claude Code local session history files including deleted or missing chat artifacts.
What do I get? / Deliverables
You identify relevant session files, analyze them, and recover extracted content using the documented JSONL format and helper scripts.
- Recovered session content extracts
- Session search and analysis results from history files
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build agent-tooling is where Claude Code session artifacts matter daily; recovery is the primary shelf before operate-style incident follow-up. Agent-tooling fits session file tooling, analyze_sessions.py search, and recover_content.py extraction against local history stores.
Where it fits
After a crashed session, search JSONL history for the last good implementation block before re-applying it to the repo.
Recover agent-generated README drafts that were never written to disk from an earlier session file.
Compare session transcripts to understand which agent steps led to a bad config change.
How it compares
Local session forensics skill with scripts—not a git reflog tool and not a general IDE local-history plugin.
Common Questions / FAQ
Who is claude-code-history-files-finder for?
Solo developers using the daymade claude-code-skills marketplace who store Claude Code sessions locally and need to search or recover prior agent output.
When should I use claude-code-history-files-finder?
During Build when recovering lost snippets from today's sessions, or during Operate when auditing what an agent proposed before an incident; run after you know history files should exist on disk.
Is claude-code-history-files-finder safe to install?
Scripts read local session files which may contain secrets; confirm status in the Security Audits panel on this page and scan recovered content before re-pasting into repos.
SKILL.md
READMESKILL.md - Claude Code History Files Finder
# Claude Code History Files Finder - Integration Summary ## ✅ Successfully Integrated into claude-code-skills Marketplace ### Changes Made #### 1. Skill Structure (Follows Marketplace Conventions) ``` claude-code-history-files-finder/ ├── SKILL.md # Main skill instructions (314 lines) ├── .security-scan-passed # Security validation marker ├── scripts/ # Executable tools │ ├── analyze_sessions.py # Session search and analysis │ └── recover_content.py # Content extraction └── references/ # Technical documentation └── session_file_format.md # JSONL structure reference ``` **Removed**: - ❌ README.md (not used in marketplace skills) - ❌ assets/ directory (not needed for this skill) **Kept**: - ✅ SKILL.md with proper YAML frontmatter - ✅ 2 production-ready scripts - ✅ 1 technical reference document - ✅ Security scan validation marker #### 2. Marketplace Registration **File**: `.claude-plugin/marketplace.json` **Added entry**: ```json { "name": "claude-code-history-files-finder", "description": "Find and recover content from Claude Code session history files...", "source": "./", "strict": false, "version": "1.0.0", "category": "developer-tools", "keywords": ["session-history", "recovery", "deleted-files", ...], "skills": ["./claude-code-history-files-finder"] } ``` **Updated metadata**: - Version: `1.11.0` → `1.12.0` - Skills count: 18 → 19 - Added "session history recovery" to description #### 3. README.md Updates **File**: `README.md` Updated badges: - Skills count: 18 → 19 - Version: 1.11.0 → 1.12.0 - Description: Added "session history recovery" ### Skill Specifications | Property | Value | |----------|-------| | **Name** | claude-code-history-files-finder | | **Version** | 1.0.0 | | **Category** | developer-tools | | **Package Size** | 12 KB | | **SKILL.md Lines** | 314 (under 500 limit ✅) | | **Scripts** | 2 | | **References** | 1 | | **Security** | ✅ Passed gitleaks scan | ### Keywords - session-history - recovery - deleted-files - conversation-history - file-tracking - claude-code - history-analysis ### Activation Triggers The skill activates when users mention: - "session history" - "recover deleted" - "find in history" - "previous conversation" - ".claude/projects" ### Core Capabilities 1. **Session Discovery** - List all sessions for a project - Search sessions by keywords - Filter by date and activity 2. **Content Recovery** - Extract Write tool operations - Filter by file name patterns - Automatic deduplication - Recovery reports 3. **Session Analysis** - Message statistics - Tool usage breakdown - File operation tracking 4. **Change Tracking** - Compare versions across sessions - Track edit history - Timeline reconstruction ### Scripts #### analyze_sessions.py **Commands**: ```bash # List sessions python3 scripts/analyze_sessions.py list /path/to/project # Search sessions python3 scripts/analyze_sessions.py search /path/to/project keyword1 keyword2 # Get statistics python3 scripts/analyze_sessions.py stats /path/to/session.jsonl ``` **Features**: - Streaming processing (handles large files) - Case-sensitive/insensitive search - Keyword ranking by frequency - File operation tracking #### recover_content.py **Usage**: ```bash # Recover all content python3 scripts/recover_content.py /path/to/session.jsonl # Filter by keywords python3 scripts/recover_content.py session.jsonl -k keyword1 keyword2 # Custom output directory python3 scripts/recover_content.py session.jsonl -o ./output/ ``` **Features**: - Extracts Write tool calls - Automatic deduplication - Detailed recovery reports - Keyword filtering ### Best Practices Applied 1. ✅ **Conciseness**: SKILL.md under 500 lines 2. ✅ **Progressive Disclosure**: - Metadata (~100 words) - SKILL.md (314 lines) - References loaded on-demand 3. ✅ **Security First**: Passed gitleaks scan 4. ✅ **Cl