session-finder

Session Finder

Overview

This skill enables searching through Claude Code session history to find previous conversations based on actual content, not just metadata. It provides accurate search results by parsing session JSONL files and ranking matches by relevance score.

When to Use This Skill

Use this skill when the user requests:

• "Find sessions where I worked on [topic]"
• "Search for sessions that edited [filename]"
• "Show me sessions about [feature/bug/task]"
• "Find when I used [tool name]"
• "Resume the session where I worked on [something]"

Quick Start

To search sessions, execute the scripts/search_sessions.py script:

python3 scripts/search_sessions.py "search terms" [optional-project-path]

Examples:

# Search current project for Pino log rotation work
python3 scripts/search_sessions.py "pino log rotation"

# Search specific project for authentication sessions
python3 scripts/search_sessions.py "authentication JWT" /Users/username/Dev/myproject

# Find sessions that edited config files
python3 scripts/search_sessions.py "config.ts"

# Find WebSocket-related work
python3 scripts/search_sessions.py "websocket refactor"

How It Works

Search Process

1. Parse search terms - Split the search description into keywords
2. Locate session directory - Find the Claude sessions directory for the project
3. Scan JSONL files - Parse each session file line-by-line
4. Filter content - Search only message.content fields (not metadata)
5. Score matches - Rank results by relevance:
   • Tool name matches: +2 points
   • Tool input matches: +1 point
   • Text content matches: +1 point per keyword
   • Tool result matches: +0.5 points
6. Display results - Show top 5 sessions with context and resume commands

What Gets Searched

Included (high-value signals):

• Message text content (user and assistant messages)
• Tool names (Read, Write, Edit, Bash, etc.)
• Tool inputs (file paths, command arguments, etc.)
• Tool results (command output, file content, etc.)