claude-session-archaeology

Reconstruct project work history by mining Claude Code session transcripts with streaming grep and jq recipes.

3|1|Updated Apr 8, 2026
One-click install
npx skills add https://github.com/ever-just/agentskills --skill claude-session-archaeology-ever-just
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: claude-session-archaeology
Source: https://github.com/ever-just/agentskills/tree/main/skills/claude-session-archaeology
Command: npx skills add https://github.com/ever-just/agentskills --skill claude-session-archaeology-ever-just

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Claude Code session transcripts are the only record of decisions, uncommitted work, and unresolved incidents, but they routinely reach 130-150 MB and cannot be opened directly, and embedded boilerplate (CLAUDE.md, MEMORY.md) makes naive keyword searches produce thousands of false positives. ## Core Features & Use Cases - Streaming transcript analysis: jq and grep recipes for extracting session titles, date ranges, user requests, shipped-work markers, and end-of-session outcomes from files up to 150 MB without loading them into context. - Boilerplate calibration and classification: verify keywords against CLAUDE.md and MEMORY.md, calibrate hit-count thresholds, and tag sessions as core, partial, or incidental to eliminate false positives. - Fork detection and fan-out strategy: detect forked session lineages to avoid double-counting, sweep nested subagent transcripts, and split work across agents by directory and filename range. - Use Case: When asked "what have we done on project X?", sweep all project directories, calibrate against boilerplate, classify the high-scoring sessions, and produce a structured JSON history with date ranges, workstreams, and key outputs. ## Quick Start Reconstruct everything we have done on this project by mining my Claude Code session transcripts in ~/.claude/projects, calibrating out boilerplate hits first.

Frequently Asked Questions about claude-session-archaeology

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search Claude Code session transcripts for past work?▼

Session transcripts live in ~/.claude/projects/<mangled-cwd>/<session-uuid>.jsonl. Use streaming grep and jq recipes to extract titles, date ranges, and user requests rather than opening the files, since they routinely reach 130-150 MB.

Why does my keyword search match every Claude session transcript?▼

Every session embeds global boilerplate, including CLAUDE.md and the auto-memory index MEMORY.md, which summarizes past work and contains common project nouns. Grep those files for your keyword first and calibrate a hit-count threshold before trusting any match.

How do I read a 150 MB JSONL transcript without crashing the agent?▼

Never load the whole file into context. Use jq with 2>/dev/null guards for titles and messages, grep -o for markers like PR numbers, and tail -c 3000000 to inspect only the end of the session where outcomes are recorded.

Where are Claude Code subagent and workflow transcripts stored?▼

Subagent and workflow transcripts live nested deeper than the main session files, at depth 3 or more under ~/.claude/projects. They can vastly outnumber main sessions, so measure both with find at maxdepth 2 and mindepth 3 before scoping a search.

How do I avoid double-counting forked Claude sessions?▼

Detect forks by comparing date ranges, hit counts, and shared early content across large files with near-identical profiles. Report one thread per lineage and note the forks instead of counting each forked file as separate work.