claude-code-history-files-finder

Claude Code History Files Finder

Search and recover content from Claude Code session history stored in active homes and explicitly registered long-term archives.

Capabilities

• Recover exact captured bytes for deleted or lost files from file-history snapshots, including files changed after their original Write call
• 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

Completeness invariant

A normal history search must cover both source classes:

1. auto-discovered active homes (~/.claude, profile homes, and the current CLAUDE_CONFIG_DIR), and
2. every archive registered in ~/.claude/history-sources.json.

Do not conclude that a session, topic, file, or action is absent unless the command output confirms that the registered archives were searched. A required archive that is unavailable is a hard configuration error. --home and --main-only are exact diagnostic scopes that intentionally bypass the archive registry; results from either flag cannot support a whole-history absence claim.

A complete source set is necessary but not sufficient — three more failure modes produce a false "not found" even with every source covered, and each has a dedicated widening (the script prints these automatically on zero matches):

1. Wrong project guess. You searched one project, the conversation lived in another. Widening: --all-projects sweeps every project in one pass.
2. Wrong tool. The conversation happened in Codex, whose rollouts are a separate store the Claude registry never covers. Widening: --codex.
3. Wording drift. A remembered quote differs from the real wording in punctuation or a few words, so the exact phrase misses. Widening: retry shorter distinctive substrings.

One trap pairs with all three: the current session always matches the phrase you just typed (the skill args, your commands, and this reasoning all land in its records). A top hit whose range starts a few minutes ago is almost certainly this session — confirm with the internal range, then rerun with --exclude-session <id> to see the real results.

Session File Locations

Each Claude history root stores sessions at <history-root>/projects/<encoded-project-path>/<session-id>.jsonl. Active roots are discovered automatically. Durable archive roots are configured once in ~/.claude/history-sources.json and then included by default.

Claude may also keep checkpoint payloads at <history-root>/file-history/<session-id>/<opaque-backup-name>. The JSONL's file-history-snapshot.snapshot.trackedFileBackups map connects each original path to its opaque backup name and version. This companion store is separate from projects/: copying only a JSONL into a long-term archive does not prove its checkpoint bytes were copied too. The format is an observed Claude Code runtime detail rather than a documented stable API, so the bundled recovery parser validates the selected mapping, version/name agreement, path containment, and byte identity, then fails visibly when those facts disagree.

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 that a project has no history, run the bundled command with its default source set. Do not infer absence from a failed ls:

python3 scripts/analyze_sessions.py list /path/to/project
python3 scripts/analyze_sessions.py search /path/to/project '<keyword>'

A ls <basename> that returns nothing means the lookup used the wrong name, NOT that history is absent. The bundled analyze_sessions.py expands ~, resolves an absolute path, falls back to an unambiguous basename reverse lookup, and searches every configured source. Prefer passing it the full absolute project path; ~, relative paths, and bare names are also accepted.

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/.

Active profiles and long-term archives — searched together by default

~/.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

Long-term archives are a second independent source class. Active directories can retain only recent sessions, while an archive keeps older JSONL files after they disappear from the active tree. A search limited to active homes can therefore produce the same false negative as a main-home-only search.

analyze_sessions.py handles both classes: list and search auto-discover every active home and load the archive registry, de-duplicate sessions by ID, union the internal range across copies, and retain every source label as provenance. Keyword search streams every physical copy and de-duplicates identical records, so an archive-only record cannot disappear merely because a newer active copy has the same session ID. Scope it only for a deliberate diagnostic:

# default: active homes + registered archives
scripts/analyze_sessions.py search /path/to/project keyword

# exact diagnostic scope; not a completeness check
scripts/analyze_sessions.py search /path/to/project keyword --main-only

# exact diagnostic scope (repeatable)
scripts/analyze_sessions.py search /path/to/project keyword --home ~/.claude-profiles/kimi

# test a non-default source registry
scripts/analyze_sessions.py search /path/to/project keyword \
  --history-sources /path/to/history-sources.json

Do not use an ad hoc raw grep to prove absence. It must independently parse the registry, cover every active root, search non-message event payloads, and apply dates to internal record timestamps; the bundled script already does so.

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 sessions ordered by their maximum internal JSONL timestamp, with the full internal range, size, path, and source provenance. File mtime is never used.

Optional: --limit N to show only N sessions (default: 10), and --from-date or --to-date to keep sessions whose internal range overlaps the requested window. --all-projects lists every project (grouped by encoded project name); --exclude-session <id> (repeatable) skips sessions.

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 and matching-record internal time ranges
• Matching field types, session provenance, and match provenance
• Primary matching path plus any other matching copies

Search covers messages, thinking text (not signatures), tool inputs/results, queue-operation content, attachments, last prompts, system/summary content, custom titles, and original paths in file-history snapshots. Optional: --case-sensitive for exact casing; --from-date and --to-date constrain matching records by their own internal timestamps, not by session mtime. --exclude-session <id> (repeatable) drops sessions — pass the current session's id whenever you search for a phrase you just typed, because your own command makes this session match.

Date-only bounds cover the whole local calendar day. Datetime bounds must carry Z or an explicit UTC offset. Records without a valid internal timestamp are excluded with a visible note while a date filter is active; never substitute file mtime after a migration or copy.

2a. Search when the project is unknown — --all-projects

The required project argument encodes a guess; when the guess is wrong, a project-scoped search reports a false "not found". Drop the positional and sweep every project instead (list accepts the same flag):

python3 scripts/analyze_sessions.py search --all-projects 'some phrase'

With --all-projects, every positional term is a keyword, so multi-keyword search is valid: search --all-projects keyword1 keyword2. Without that flag, the first positional is the project path and the remaining terms are keywords.

Expected output: one pass over every project's sessions across all sources, with a Project: line naming the encoded project dir on each hit. This is a full-history sweep — expect minutes, not seconds, on a large tree.

2b. Include Codex history — --codex

Claude Code is not the only tool with history. Codex keeps rollouts at <codex-home>/sessions/<YYYY>/<MM>/<DD>/rollout-*.jsonl plus archived_sessions/ (codex home = --codex-home, $CODEX_HOME, or ~/.codex). Their schema differs from Claude's, so the default search skips them entirely; --codex adds a rollout pass:

python3 scripts/analyze_sessions.py search /path/to/project 'some phrase' --codex

Codex hits print in their own section (📦) with session id, cwd, internal ranges, mention counts, and match fields. A project positional filters rollouts by their session_meta cwd (recursive match); with `--all-pro

---

Content truncated.