claude-sessions

Local-only search and resume for Claude Code sessions, exposed to Claude itself over MCP. Nothing leaves the machine: transcripts are mirrored to ~/.claude-sessions/archive/ (0600 files) and indexed in ~/.claude-sessions/index.db (SQLite FTS5).

Tools Claude gets

• search_sessions — hybrid search across every project; empty query lists recent sessions; filter by project substring or date; returns the total match count and pages with offset.

  • Exact: a session matches when every word appears anywhere in it (any message, command output, subagent work, or Claude Code's generated title). Whole words, stemmed forms, word starts and any substring of 3+ characters all match; "quotes" for phrases. Filler words are ignored unless quoted. With 3+ words, sessions missing one word are kept too (labelled words 4/5). Ranking is BM25 at session level, so long sessions don't win just by being long.

  • Meaning (optional local model, see below): finds sessions about the same thing in different words.

  • The two rankings are merged (reciprocal rank fusion); each result says how it matched.

• read_session — paged transcript, so Claude can answer questions about an old session or carry its context into the current one.

• open_session — restores the transcript if Claude Code's cleanup deleted it, then runs claude --resume <id> in the original directory in a new tmux window (if you're in tmux), a split pane beside the current one (iTerm), or a new terminal window (macOS Terminal, GNOME Terminal, Konsole). Otherwise it returns the command.

Related MCP server: ccfolio

Install

With Claude Code (recommended): paste this into Claude Code.

Clone https://github.com/Mitrajit/claude-sessions into ~/code/claude-sessions and follow its INSTALL.md exactly; show me the settings.json diff before applying it.

By hand:

git clone https://github.com/Mitrajit/claude-sessions ~/code/claude-sessions && cd ~/code/claude-sessions
npm ci && npm run build && npm install -g .
claude-sessions setup            # preview the settings.json + MCP changes for this machine
claude-sessions setup --apply    # make them (settings.json is backed up first)
claude-sessions index

setup adds three things to ~/.claude/settings.json: cleanupPeriodDays: 365, a SessionEnd hook that archives each session as it ends, and permission to use search_sessions / read_session without prompting. It also registers the MCP server. It uses absolute paths to node, because hooks and MCP servers don't always inherit a PATH that has it (nvm, desktop app). Every tool call also syncs, so the hook is a safety net, not a requirement. open_session is left off the allow list so opening a terminal still asks first.

Optional line for ~/.claude/CLAUDE.md:

When I refer to a previous session or chat, use the claude-sessions tools to find it instead of asking me for context.

Check it from a shell: claude-sessions search retry webhook

Search by meaning (manual model install)

The model is never downloaded by the tool. Put these four files from https://huggingface.co/Xenova/bge-small-en-v1.5/tree/main into ~/.claude-sessions/models/Xenova/bge-small-en-v1.5/, keeping the onnx/ subfolder:

config.json
tokenizer.json
tokenizer_config.json
onnx/model_quantized.onnx      (~34 MB)

Then run claude-sessions index once to embed existing sessions; after that new messages are embedded on each sync. Without the model, search is exact-only and says so.

Measuring search quality

claude-sessions eval [samples] samples text from real sessions, searches for it, and reports how often the source session comes back (exact words, word starts, substrings, command output, subagent work, and session titles as paraphrased queries). Re-run it after changes and after Claude Code updates, since the transcript format is undocumented.

Env vars

• CLAUDE_CONFIG_DIR — Claude Code's config dir (default ~/.claude)

• CLAUDE_SESSIONS_HOME — archive + index location (default ~/.claude-sessions)

• CLAUDE_BIN — command used to resume (default claude)

• CLAUDE_SESSIONS_RETENTION_DAYS — archived sessions idle longer than this are deleted (default 365)

• CLAUDE_SESSIONS_MODEL_DIR — where the embedding model lives (default ~/.claude-sessions/models)

• CLAUDE_SESSIONS_MIN_SIMILARITY — cutoff for meaning-only matches (default 0.68, calibrated with eval)

Notes

• Resume works per directory: if the original folder was moved or deleted, open_session says so and gives the command to run once it's back at that path. read_session works regardless.

• Slash-command noise is skipped. Tool output and subagent work are indexed for exact search but rank below the conversation itself; tool output can be read with include_tool_results.

• Transcripts are plain text and can contain anything you pasted, including secrets.