find-conversation: Search Your Claude Code History

Why I Built This

I use Claude Code a lot. Across multiple projects, multiple repos, hundreds of conversations. And every now and then I need to find that one session where I debugged a deployment issue, or where I discussed a specific design decision, or where I wrote a tricky migration script.

Claude Code stores all conversations as JSONL files under ~/.claude/projects/. But there's no built-in way to search through them. So I built one.

find-conversation is a Claude Code plugin. You type /find-conversation deployment vercel and it searches every conversation you've ever had, ranks the results, and gives you resume commands to jump right back in.

The Problem

Claude Code saves conversations in JSONL files organized by project path. The folder names are URL-encoded versions of your filesystem paths. Once you've accumulated a few hundred sessions across a dozen projects, finding anything specific is basically impossible without manually grepping through encoded directory names and raw JSON.

You know the conversation exists somewhere. You remember roughly what you discussed. But good luck finding it.

How It Works

The plugin is pure Python (3.8+, zero external dependencies) and optimized to be fast even with large conversation histories.

Step 1

Scan for conversation files

Walks ~/.claude/projects/ and finds all JSONL conversation files. Decodes the URL-encoded folder names to reconstruct the original project paths so results are human-readable.

Step 2

Binary pre-filtering

Before parsing any JSON, it scans files in 1MB binary chunks looking for your search terms as raw bytes. Files that don't contain your keywords at all get skipped entirely. This alone saves a ton of time.

Step 3

Single-pass parsing

Files that pass the binary filter get parsed line by line in a single pass. No loading the entire file into memory, no building full ASTs. Just stream through, extract the text content, count matches.

Step 4

Smart noise filtering

System reminders, notification messages, and other noise get filtered out. Only real user and assistant messages are searched, so you get results that actually matter.

Step 5

Ranked results

Results are ranked by match frequency and limited to the top 10. Each result shows the session slug, match count, project path, timestamps, and a claude --resume command you can copy and run.

Installation

Install it from the Claude Code plugin marketplace:

        /plugin marketplace add akzarma/claude-find-conversation
/plugin install find-conversation@akzarma-tools
      

Usage

Just type /find-conversation followed by your search terms:

        /find-conversation deployment vercel
/find-conversation database migration
/find-conversation React optimization
      

It returns formatted results with everything you need to jump back into the session. The resume command is right there, just copy and paste.

Key Features

Efficient binary pre-filtering before full JSON parsing
Smart path decoding that reconstructs filesystem paths from Claude's encoded folder names
Filters out system noise to surface only real conversations
Ranked results with match counts and resume commands
Pure Python 3.8+, zero external dependencies
Works on macOS and Linux
MIT licensed

Try It

The plugin is open source. Install it, search your history, find that conversation you forgot about.

View on GitHub