cc-conversation-search 0.4.8

Find and resume Claude Code conversations using smart hybrid extraction and JIT indexing

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]

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

cc-conversation-search tree

View conversation tree structure

cc-conversation-search tree SESSION_ID [--json]

Architecture

~/.claude/
├── projects/           # Claude Code conversation files (JSONL)
│   └── {project}/
│       └── {session}.jsonl
└── skills/
    └── conversation-search/  # Optional Skill

~/.conversation-search/
└── index.db           # SQLite database with indexed conversations

Key Purpose: Find session IDs and project paths to resume past conversations.

Database Schema

• messages: Individual messages with summaries, tree structure (parent_uuid), timestamps
• conversations: Session metadata with conversation summaries
• message_summaries_fts: FTS5 full-text search index
• index_queue: Processing queue for batch operations

How It Works

1. Indexer: Scans ~/.claude/projects/ for JSONL conversation files, parses tree structure
2. Smart Extraction: Hybrid approach - full user content + first 500/last 200 chars for assistant
3. Meta-Conversation Filtering: Automatically detects and excludes conversations where Claude used the search tool (prevents search results pollution)
4. Search: FTS5 full-text search over extracted content with conversation tree traversal
5. Calendar Date Filtering: Intuitive date parameters (--date yesterday) using SQLite date functions
6. JIT Indexing: Skill runs index before search for fresh data (instant, no AI calls)
7. Local Timezone Display: All timestamps converted to your local timezone for readability

Claude Code Skill

The included Skill allows Claude to search your conversation history automatically.

Example usage:

Topic-based query:

User: "Find that conversation where we started implementing the API"
Claude: [Activates conversation-search Skill]
        [Classifies as Topic query]
        [Runs: cc-conversation-search search "implementing API" --days 14 --json]
        [Finds match]
        [Displays session ID, project path, and resume commands]

        Output:
        Session: abc-123-session-id
        Project: /home/user/projects/myproject
        Time: 2025-11-13 22:50 (local time)

        To resume:
          cd /home/user/projects/myproject
          claude --resume abc-123-session-id

Temporal query (NEW in v0.4.8):

User: "What did we work on yesterday?"
Claude: [Activates conversation-search Skill]
        [Classifies as Temporal query]
        [Runs: cc-conversation-search list --date yesterday --json]
        [Analyzes conversations by project]

        Output:
        Yesterday's work summary:

        Project: /home/user/projects/api-service
        - Implemented Redis caching layer
        - Fixed authentication timeout bug
        Session: def-456-session-id

        Project: /home/user/projects/frontend
        - Updated React components for new API
        Session: ghi-789-session-id

See skills/conversation-search/SKILL.md for progressive search workflow and complete documentation.

Advanced Usage

JSON Output for Scripting

All commands support --json flag:

# Export search results
cc-conversation-search search "authentication" --json > auth_convs.json

# Programmatic processing
cc-conversation-search list --days 30 --json | jq '.[] | .conversation_summary'

Programmatic Use

from conversation_search.core.search import ConversationSearch
from conversation_search.core.indexer import ConversationIndexer

# Search for messages with calendar date filtering
search = ConversationSearch()

# Traditional relative time
results = search.search_conversations("authentication", days_back=7)

# New calendar date filtering (v0.4.8+)
results = search.search_conversations("authentication", date="yesterday")
results = search.search_conversations("auth", since="2025-11-10", until="2025-11-13")

for r in results:
    print(f"{r['message_uuid']}: {r['summary']}")

# List conversations by date
convs = search.list_recent_conversations(date="yesterday")
convs = search.list_recent_conversations(since="2025-11-10", until="today")

# Index conversations
indexer = ConversationIndexer()
indexer.index_all(days_back=7)
indexer.close()

Configuration

Database location: ~/.conversation-search/index.db

No configuration file needed - all settings via command-line flags.

Performance

• Smart Extraction: Instant (no AI calls), deterministic
• Indexing Speed: ~1000+ messages/second (no API latency)
• Storage: ~1-2KB per message (extracted text + metadata)
• Search Speed: SQLite FTS5 is very fast, even with 100K+ messages
• Cost: $0 (no AI API calls during indexing)

Development

Setup

git clone https://github.com/akatz-ai/cc-conversation-search
cd cc-conversation-search
uv tool install -e .

Run Tests

pytest tests/

Project Structure

conversation-search/
├── src/
│   └── conversation_search/
│       ├── __init__.py
│       ├── cli.py              # Unified CLI
│       ├── core/
│       │   ├── indexer.py      # Conversation indexing + meta-filtering
│       │   ├── search.py       # Search functionality + date filtering
│       │   ├── date_utils.py   # Calendar date parsing (v0.4.8+)
│       │   └── summarization.py # Smart hybrid extraction
│       └── data/
│           └── schema.sql      # Database schema
├── skills/
│   └── conversation-search/
│       ├── SKILL.md           # Claude Code Skill with query classification
│       └── REFERENCE.md       # Complete command reference
├── tests/
│   ├── test_date_utils.py     # Date parsing tests
│   ├── test_date_filtering.py # Date filter integration tests
│   └── test_search_pair_detection.py # Meta-filtering tests
├── pyproject.toml
└── README.md

Troubleshooting

"Database not found" error:

cc-conversation-search init

"No conversations found":

• Verify ~/.claude/projects/ exists and contains JSONL files
• Use Claude Code to create some conversations first

Want to skip extraction and use raw content only:

# Store only raw content (even faster, but less optimized for search)
cc-conversation-search init --no-extract

Skill not activating:

• Check Skill location: ls ~/.claude/skills/conversation-search/SKILL.md
• Verify YAML frontmatter format
• Restart Claude Code
• Try explicit trigger: "Search my conversations for X"

Import errors:

uv tool uninstall cc-conversation-search
uv tool install cc-conversation-search

Contributing

PRs welcome! This is an experimental tool to improve Claude Code workflow.

Areas for Contribution

• Vector embeddings for semantic similarity search
• Web UI for conversation tree visualization
• Export conversation branches as markdown
• Conversation analytics (topics, frequency, etc.)
• Additional Claude Code Skills using the search API

License

MIT

Acknowledgments

Built for the Claude Code ecosystem. Uses smart hybrid extraction for instant, cost-free indexing.