session-finder — Claude Code skill: search past sessions
session-finder indexes your past Claude Code sessions with Gemini embeddings, then pulls up the one you mean from a plain description of the task.
MIT 166 installs ★ 414 updated 2026-10-23
npx skills add glebis/claude-skills --skill session-finder -a claude-codeWhat session-finder does
The skill brings session_finder.py with four subcommands: index, search, open, stats. Indexing parses each session JSONL with no model in the loop. It keeps the pre-existing away_summary recaps, the first user message that states the task, condensed follow-ups, the opening assistant reply, tool names and the project name.
Those documents get embedded with gemini-embedding-exp-03-07 through the llm CLI and stored in SQLite at ~/.claude/session-finder.db. A search embeds the query, ranks every session by cosine similarity and prints confidence scores. open jumps to the top hit right away; inside a conversation the skill offers claude --resume <id> instead. --max-age-days caps indexing by session age, --top sets how many results come back.
History is read from ~/.claude, so on Cursor, Codex or Gemini CLI you are still searching Claude Code sessions rather than that editor's own history. Python 3 and the llm CLI with Gemini access are required.
What it helps with
- find the session where you changed the schema migration
- pick up an abandoned task where you left it
- index only recent sessions
- open the best match without a second search
- check how many sessions sit in the index
Example prompts for the agent
- Find the session where I set up the deploy in
fly.toml - Which session did I work on the log parser?
- Relaunch the session where we fixed the failing tests
How to install session-finder
1Skills CLI (Vercel)
npx skills add glebis/claude-skills --skill session-finder -a claude-code2Manually: put the files in place
~/.claude/skills/session-finder/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/session-finder/
1Skills CLI (Vercel)
npx skills add glebis/claude-skills --skill session-finder -a codex2Manually: put the files in place
.agents/skills/session-finder/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add glebis/claude-skills --skill session-finder -a cursor2Manually: put the files in place
.cursor/skills/session-finder/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install glebis/claude-skills session-finder2Manually: put the files in place
.github/skills/session-finder/SKILL.md1Skills CLI (Vercel)
npx skills add glebis/claude-skills --skill session-finder -a gemini-cli2Platform CLI
gemini skills install https://github.com/glebis/claude-skills --path session-finderManually: put the files in place
.devin/skills/session-finder/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add glebis/claude-skills --skill session-finder -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about session-finder
How do I install session-finder in Claude Code?
Run npx skills add glebis/claude-skills --skill session-finder -a claude-code. The skill then sits at ~/.claude/skills/session-finder/SKILL.md.
What does session-finder do?
It builds documents from earlier Claude Code sessions, embeds them, and matches your query by meaning. The top result can be opened or resumed with claude --resume.
What do I need for it to work?
Python 3 and the llm CLI with access to Gemini embeddings. The index lives in ~/.claude/session-finder.db.
Source text
SKILL.md · MIT
--- name: session-finder description: Index and search Claude Code sessions using semantic embeddings (Gemini). Find past sessions by topic, relaunch the best match. Triggers on "find session", "which session did I", "relaunch the session where", "session about X". --- # Session Finder Semantic search across Claude Code sessions using Gemini embeddings. ## Commands ### Index sessions ```bash python3 ~/.claude/skills/session-finder/scripts/session_finder.py index [--max-age-days 90] ``` ### Search ```bash python3 ~/.claude/skills/session-finder/scripts/session_finder.py search "query" [--top 5] ``` ### Open best match directly ```bash python3 ~/.claude/skills/session-finder/scripts/session_finder.py open "query" ``` ### Stats ```bash python3 ~/.claude/skills/session-finder/scripts/session_finder.py stats ``` ## How it works 1. **Document extraction** — deterministic, no LLM. Each session JSONL is parsed into a structured document: - `away_summary` events (pre-existing Claude recaps) if available - First user message (task description) - Follow-up user messages (condensed) - First assistant response - Tools used - Project name 2. **Embedding** — documents are embedded with `gemini-embedding-exp-03-07` via `llm` CLI 3. **Storage** — SQLite at `~/.claude/session-finder.db` 4. **Search** — query is embedded, cosine similarity ranks all sessions, top match is the default to open ## Workflow When user asks to find a session: 1. Run `search` with their query 2. Present results with confidence scores 3. Offer to resume the top match via `claude --resume <id>`
© glebis · MIT · glebis/claude-skills