Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add glebis/claude-skills --skill session-finder -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/session-finder/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/session-finder/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set51

The whole set →

Project sponsors

Companies that keep this analytics open