Thread Finder

Thread Finder (Claude Code edition)

Thread Finder makes your local Claude Code session history reusable. It scans ~/.claude/projects/, indexes the JSONL transcripts (including tool calls and tool results), and searches them with hybrid BM25 + vector retrieval. It understands time-based questions ("what did I do last week"), keeps itself current by topping up the index at query time, extracts a prior session into paste-ready context, and pulls out the files and links a session referenced.

It runs on both Linux and macOS, and is a port of the Codex thread-finder plugin rewritten against Claude Code's filesystem-based session storage.

What It Indexes

• All *.jsonl files under ~/.claude/projects/<encoded-cwd>/
• user and assistant events, with text, tool_use (name + truncated input), and tool_result (truncated content) blocks. thinking blocks are skipped.
• Sidechain (sub-agent) sessions are included and tagged via is_sidechain.

A session is eligible for indexing once its transcript file has been idle for at least 10 minutes, so the live session is never indexed mid-write.

Install

Add the marketplace and install the plugin:

/plugin marketplace add Hyatus-Living/claude-plugins
/plugin install thread-finder@hyatus-claude-plugins

Then provide an OpenAI API key (used for embeddings; text-mode search works without one). Run the bundled thread-finder-setup skill, or set it yourself. The key is read from the first available source: the OPENAI_API_KEY environment variable, a ~/.claude/.env file (OPENAI_API_KEY=sk-...), the macOS login keychain (service thread-finder-openai), or the Linux Secret Service via secret-tool. The simplest cross-platform option:

umask 177 && printf 'OPENAI_API_KEY=%s\n' 'sk-...' > ~/.claude/.env

Restart the Claude Code session so the MCP server picks up the key. The server runs under uv and uses numpy for fast vector search (uv run --with mcp --with numpy).

How Search Stays Current

• Live freshness: a search tops up the index with the newest unindexed sessions before returning, scoring them lexically (no embeddings), so recent work shows up even if you have not re-indexed. Controlled by freshness_live_limit (default 25; 0 disables).
• Vector cache: chunk embeddings are kept as a memory-mapped numpy matrix next to the index, so vector search is a single matrix multiply instead of decoding every row per query. The cache is rebuilt automatically when the index changes.
• Freshness tools: thread_finder_status and thread_index_freshness report how stale the index is; thread_index_freshness_gaps backfills the newest gaps within a time budget.

MCP Tools

Search & extract

• thread_search(query, limit=5, mode="hybrid", project=None, freshness_live_limit=25) — hybrid (vector + BM25/RRF), text (BM25 only; best for IDs, paths, filenames, function names), or vector (semantic only). Understands temporal phrasing and applies a date window. project is a substring filter against the encoded project dir or decoded cwd. A query containing a session UUID short-circuits to that session.
• thread_query_plan(query, mode="hybrid", now_ts=None) — show the parsed temporal intent, cleaned retrieval query, and planned mode without running a search.
• thread_extract(thread_id, include_transcript=false) — paste-ready context for a session, including referenced artifacts.
• thread_artifact_list(thread_id, limit=50, extensions=None, exists_only=false, include_system_paths=false) — the local file paths and URLs a session referenced.
• thread_artifact_search(query, thread_limit=5, artifact_limit=20, mode="hybrid", extensions=None, ...) — find prior sessions and return their referenced artifacts, with file-type inference (e.g. "the spreadsheet I exported").

Index & maintenance

• thread_index_sync(force=false, limit=null, project=None, max_seconds=None) — index idle sessions.
• thread_index_one(thread_id, force=false, max_seconds=None) — index or re-index one session.
• thread_index_freshness(limit=20) — list eligible sessions missing from or stale in the index.
• thread_index_freshness_gaps(limit=20, force=true, max_seconds=None) — index only the newest gaps, within a time budget.
• thread_finder_status() — index freshness, model, vector-cache, and source-session health.
• thread_index_integrity() — verify thread / chunk / FTS row consistency.
• thread_finder_maintenance(vacuum=false, prune_vector_cache=false, rebuild_vector_cache=false) — clean stale FTS rows, vacuum, rebuild the vector cache.
• thread_temporal_eval_suite(case_id=None, now_ts=None) — run the deterministic temporal-parser evals.
• thread_finder_paths() — projects root, index path, embedding model, vector-cache stats, plugin root.

CLI Usage

The core is also a CLI (python3 ${CLAUDE_PLUGIN_ROOT}/scripts/thread_finder_core.py <command>):

# search (hybrid / text / vector), optionally scoped or time-bounded
... search "pricing deploy rollback" --mode hybrid
... search "multiunit_attributes 4699138" --mode text
... search "rentals united import" --project accounting-analytics
... search "worktree cleanup last week"

# explain how a query is planned
... plan "since 2026-05-29 PR worktree cleanup"

# index management
... index                         # index all idle sessions
... index --thread-id SESSION_ID --force
... status                        # how stale is the index?
... freshness --limit 20          # which sessions are missing/stale?
... index-gaps --limit 10 --max-seconds 60   # backfill newest gaps
... integrity
... maintenance --rebuild-vector-cache --vacuum

# context & artifacts
... extract SESSION_ID [--include-transcript]
... artifacts SESSION_ID
... artifact-search "the pdf report I generated"

Data Sources & Storage

• Read from: ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl
• Written to: ~/.claude/plugins/data/thread-finder/index.sqlite (index) and ~/.claude/plugins/data/thread-finder/vector-cache/ (derived, rebuildable)

The plugin never modifies a Claude Code session file.

Differences from the Codex Version

	Codex	Claude Code
Session catalog	state_5.sqlite threads table	Filesystem scan of ~/.claude/projects/
Title	DB column	type:"ai-title" event in the JSONL
cwd	DB column	Decoded from the project dir name, or a cwd field on any event
Archived flag	Yes	Replaced with is_sidechain
Content blocks	input_text / output_text	text, tool_use, tool_result (truncated); thinking skipped
OpenAI key	~/.codex/.env	env var, ~/.claude/.env, macOS keychain, or Linux Secret Service
Live-freshness metadata	Free from the state DB	Bounded partial read of the transcript

Pulling Context Into The Current Session

1. thread_search with the topic the user remembers.
2. Pick the matching thread_id (session ID).
3. thread_extract(thread_id).
4. Return the paste_ready_summary in the current session.
5. If the user asks for the full transcript, run thread_extract(thread_id, include_transcript=true).

Treat extracted context as historical. Re-check live code, DB rows, credentials, deploy state, and filesystem paths before treating any operational detail as current.