mcpField
S
session-index

session-index

github.com/cearleyProductivity041 installsUpdated 12w ago
Repository

About session-index

session-index is a skill for searching and analyzing a SQLite index of Claude Code sessions. It helps users revisit past discussions, inspect conversation context, and synthesize approaches across sessions through CLI commands.

Key features

  1. 01Full-text session search
  2. 02Conversation context retrieval
  3. 03Effort and tool-use analytics
  4. 04Metadata and environment filters
  5. 05Cross-session synthesis guidance

Use cases

  1. 01Find earlier discussions by topic
  2. 02Review exchanges from a past session
  3. 03Measure time spent by client or week

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/cearley/claude-session-index --skill session-index

After installing, type/session-indexin Claude Code to confirm it loaded.

Details

From the project README

Session index skill

You have access to a session index — a SQLite database with FTS5 full-text search across all Claude Code sessions. Use it whenever the user asks about past sessions, previous conversations, or wants to know what they've tried before.

The user's interface is this conversation. They ask naturally ("Didn't we discuss browser control recently?"), you translate to CLI commands, and present results conversationally. They should never need to know the CLI syntax.

How to handle session queries

1. Extract keywords from the question

The user says: "Didn't we discuss browser control recently?" You search: sessions "browser control"

The user says: "What approaches have I tried for form automation?" You search: sessions "form automation"

The user says: "How much time did I spend on Acme this week?" You run: sessions analytics --client "Acme" --week

2. Run the right command via Bash

Search — find sessions by topic:

sessions "relevant keywords"
sessions "relevant keywords" --context    # includes conversation excerpts

Context — read the actual conversation from a session:

sessions context <session_id> "search term"   # exchanges matching a term
sessions context <session_id>                 # all exchanges

Analytics — effort, time, tool usage:

sessions analytics                    # overall
sessions analytics --client "Acme"    # per client
sessions analytics --week             # this week
sessions analytics --month            # this month
sessions analytics --env personal     # one Claude environment

Filter — find sessions by metadata:

sessions find --client "Acme"              # by client
sessions find --tool Task --week           # by tool + date
sessions find --project myapp              # by project
sessions find --week --env work            # by date + environment
sessions recent 20                         # last N sessions
sessions recent --env personal             # one Claude environment
sessions recent --env current              # active CLAUDE_CONFIG_DIR environment

If the user mentions a specific Claude environment (personal, work, bedrock, etc.), add --env <name> to scope results. --env current resolves to CLAUDE_CONFIG_DIR at runtime. All find, recent, and analytics commands accept --env.

3. For synthesis ("what worked?", "what have I tried?")

This is the most valuable capability. When the user asks a question that spans multiple sessions:

  1. Search: sessions "topic" -n 10
  2. For the top 3-5 results, extract context: sessions context <id> "topic" -n 3
  3. Spawn a Task with model="haiku" to synthesize:
    • What approaches were tried?
    • What worked / what failed?
    • Recurring patterns?
    • Current state?
  4. Present the synthesis conversationally with claude --resume <id> links for each source session

This uses an in-session Haiku subagent — no external API key needed.

4. Present results conversationally

Don't dump raw CLI output. Summarize:

  • "You discussed browser control in 3 sessions last week..."
  • "The main approach that worked was..."
  • Include claude --resume <session_id> links so they can jump back in
  • If context is relevant, quote key exchanges

Installation

uv tool install git+https://github.com/cearley/claude-session-index

First run of any command auto-indexes all existing sessions.

Multiple Claude environments: discovered automatically — sibling ~/.claude-*/projects directories are indexed alongside the default ~/.claude/projects with no configuration needed. To index a different set, set SESSION_INDEX_PROJECTS to a colon-separated list of projects/ directories, or add projects_dirs (list) to ~/.session-index/config.json:

export SESSION_INDEX_PROJECTS=~/.claude-personal/projects:~/.claude-work/projects

The --projects-dir flag is also repeatable for one-off overrides:

sessions --projects-dir ~/.claude-personal/projects --projects-dir ~/.claude-work/projects index

Each session is tagged with an env:<name> label (derived from its source directory path).

Data location

  • Database: ~/.session-index/sessions.db
  • Topics: ~/.claude/session-topics/
  • Config: ~/.session-index/config.json (optional)

Comments

Markdown supported