conversation-search

Conversation Search

Find and resume past Claude Code conversations using smart hybrid extraction and JIT indexing. Get session IDs and project paths to easily jump back into previous work.

Features

• Session Resumption: Get exact commands to resume past conversations
• Unified CLI: Single cc-conversation-search command with intuitive subcommands
• Calendar Date Filtering: Intuitive --date yesterday, --since, --until parameters
• Smart Extraction: Hybrid indexing (full user content + smart assistant extraction)
• JIT Indexing: Instant indexing before search (no AI calls, no delays)
• Local Timezone Display: All timestamps shown in your local time
• Meta-Conversation Filtering: Automatically excludes search tool usage from results
• Progressive Exploration: Simple search → broader search → manual exploration
• Conversation Context: Expand context incrementally around any message
• Claude Code Skill: Integrated Skill that outputs session resumption commands
• Multi-Project Support: Works across all your Claude Code projects

Quick Start

Installation via Claude Code Plugin (Recommended)

Install the complete plugin (skill + CLI tool instructions) directly in Claude Code:

# Add this repo's marketplace
/plugin marketplace add akatz-ai/cc-conversation-search

# Install the plugin
/plugin install conversation-search

Then follow the installation instructions shown by Claude to:

1. Install the CLI tool: uv tool install cc-conversation-search
2. Initialize the database: cc-conversation-search init

Manual Installation

1. Install CLI Tool

# Using uv (recommended)
uv tool install cc-conversation-search

# Or using pip
pip install cc-conversation-search

2. Initialize Database

cc-conversation-search init

This creates the database and indexes your last 7 days of conversations.

3. Install Skill (Optional)

mkdir -p ~/.claude/skills/conversation-search
cp skills/conversation-search/* ~/.claude/skills/conversation-search/

Basic Usage

# Search for conversations (shows session ID and resume commands)
cc-conversation-search search "authentication bug"

# Search with calendar date filters
cc-conversation-search search "react hooks" --date yesterday
cc-conversation-search search "auth" --since 2025-11-10 --until 2025-11-13

# List conversations by date
cc-conversation-search list --date yesterday
cc-conversation-search list --since "2025-11-01"

# Traditional relative time filters still work
cc-conversation-search search "query" --days 30

# Get resume commands for a specific message
cc-conversation-search resume <MESSAGE_UUID>

# Use with uvx (no install needed)
uvx cc-conversation-search search "query"

Using with Claude Code Skill

Once installed, ask Claude:

Topic-based queries:

• "Find that conversation where we discussed authentication"
• "Locate the conversation about React hooks"
• "What did we talk about regarding the database?"

Temporal queries (NEW in v0.4.8):

• "What did we work on yesterday?"
• "Summarize today's conversations"
• "Show me this week's work"

Hybrid queries:

• "Find yesterday's authentication work"
• "Show recent Redis discussions"

Auto-Installation: If the CLI tool isn't installed, the skill will automatically attempt to install it via uv or pip, then initialize the database. In most cases, everything "just works" after installing the plugin!

Claude will show you the session ID, project path, and exact commands to resume the conversation.

Command Reference

cc-conversation-search init

Initialize database and perform initial indexing

cc-conversation-search init [--days 7] [--no-extract] [--force]

cc-conversation-search index

JIT index conversations (instant, no AI calls)

cc-conversation-search index [--days N] [--all] [--no-extract]

IMPORTANT: The skill always runs index before search for fresh data.

cc-conversation-search search

Search conversations with flexible date filtering

# Traditional relative time
cc-conversation-search search "query" [--days N] [--project PATH] [--content] [--json]

# Calendar date filtering (v0.4.8+)
cc-conversation-search search "query" --date yesterday [--json]
cc-conversation-search search "query" --date 2025-11-13 [--json]
cc-conversation-search search "query" --since 2025-11-10 --until 2025-11-13 [--json]

# Date formats: YYYY-MM-DD, "yesterday", "today"
# Note: --days cannot be combined with --date/--since/--until

cc-conversation-search context

Get context around a specific message

cc-conversation-search context MESSAGE_UUID [--depth 5] [--content] [--json]

cc-conversation-search list

List recent conversations with calendar date support

# Traditional relative time
cc-conversation-search list [--days 7] [--limit 20] [--json]