Conversation Search Skill

Conversation Search

Find past conversations in your Claude Code history and get the commands to resume them.

MANDATORY FIRST STEP - CREATE TODO CHECKLIST

Before doing ANYTHING else, you MUST use the TodoWrite tool to create this exact checklist:

- Ensure cc-conversation-search tool is installed and upgraded
- Classify query type (temporal/topic/hybrid)
- Execute Level 1: focused search with cc-conversation-search
- Execute Level 2: broader search if Level 1 fails
- Execute Level 3: manual exploration if Level 1 and 2 fail
- Present results to user

CRITICAL CONSTRAINTS:

DO NOT use grep, find, cat, or any manual file operations on .jsonl files
DO NOT skip the todo creation step
DO NOT jump to Level 3 without attempting Levels 1 and 2
ONLY use cc-conversation-search commands for all search operations

Mark each todo as in_progress when starting it, completed when done.

Prerequisites & Auto-Installation

The skill requires the cc-conversation-search CLI tool (v0.4.0+ minimum).

First todo: Ensure tool is installed and upgraded

# Check if installed and upgrade
if command -v cc-conversation-search &> /dev/null; then
    uv tool upgrade cc-conversation-search 2>/dev/null || pip install --upgrade cc-conversation-search
    echo "Upgraded to: $(cc-conversation-search --version)"
else
    # Install if needed
    if command -v uv &> /dev/null; then
        uv tool install cc-conversation-search
    else
        pip install --user cc-conversation-search
        export PATH="$HOME/.local/bin:$PATH"
    fi
    # Initialize database
    cc-conversation-search init --days 7
fi

If installation fails, guide the user:

The conversation-search plugin requires the cc-conversation-search CLI tool.

Install it manually:
  uv tool install cc-conversation-search  (recommended)
  OR
  pip install --user cc-conversation-search

Then initialize:
  cc-conversation-search init

Do not proceed with search until installation is confirmed.

Query Type Classification

Second todo: Classify the user's query

Determine which type before executing search:

Type 1: Temporal Queries

User asks about time periods WITHOUT specific topics:

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

Action: Use list command with date filters

Type 2: Topic Queries

User asks about CONTENT/TOPICS:

"Find that Redis conversation"
"Where did we discuss authentication?"
"Show me where we worked on the API"

Action: Use search "topic" command

Type 3: Hybrid Queries

User asks about TOPIC + TIME:

"Show me yesterday's authentication work"
"Find Redis discussions from last week"
"How many times did you say X in the past week?"

Action: Use search "topic" with date filters

Three-Level Search Workflow

Execute in order. Do not skip levels.

Level 1: Focused Search (ALWAYS START HERE)

Based on query classification:

For Topic or Hybrid queries:

cc-conversation-search search "search terms" --days 14 --json

For Temporal queries:

cc-conversation-search list --date yesterday --json  # or --days N, --since, --until

Parse the JSON output. If you find relevant matches → skip to Level 4 (present results).

Note: Search auto-indexes recent conversations for fresh data.

Level 2: Broader Search

Only if Level 1 found nothing useful.

For topic/hybrid queries:

Remove time constraints: cc-conversation-search search "terms" --json
Try alternative keywords: "auth" vs "authentication"
Try broader terms: "database" vs "postgres"

For temporal queries:

Expand time range: --days 30 instead of --days 7

If matches found → skip to Level 4.

Level 3: Manual Exploration

Only if Levels 1 and 2 both failed.

List conversations: cc-conversation-search list --days 30 --json
Review conversation summaries in JSON
For promising sessions: cc-conversation-search tree <SESSION_ID> --json
Read message summaries to locate content

Level 4: Present Results

Format results for the user:

For found conversations:

**Session Details**
- **Session**: abc-123-session-id
- **Project**: /home/user/projects/myproject
- **Time**: 2025-11-13 22:50
- **Message**: def-456-message-uuid (if applicable)

**To Resume This Conversation**
```bash
cd /home/user/projects/myproject
claude --resume abc-123-session-id


For counting/analysis queries:
- Parse JSON results
- Filter by message_type if needed (user vs assistant)
- Count matches
- Present clear answer with evidence

**If not found after all 3 levels:**
- "No matching conversations found after exhaustive search"
- Suggest: `cc-conversation-search index --days 90` to reindex older history
- "The conversation may not exist or may be older than indexed range"

## Command Reference

### Search (for topic and hybrid queries)
```bash
# With time scope
cc-conversation-search search "query" --days N --json

# Specific date
cc-conversation-search search "query" --date yesterday --json
cc-conversation-search search "query" --date 2025-11-13 --json

# Date range
cc-conversation-search search "query" --since 2025-11-10 --until 2025-11-13 --json

# All time
cc-conversation-search search "query" --json

Date filter options:

--days N: Last N days from now
--date DATE: Specific calendar day
--since DATE: From date onwards
--until DATE: Up to date (inclusive)
DATE formats: yyyy-mm-dd, yesterday, today
Cannot mix --days with --date/--since/--until

List (for temporal queries)

cc-conversation-search list --date yesterday --json
cc-conversation-search list --days 7 --json
cc-conversation-search list --since 2025-11-10 --until today --json

Context & Tree

cc-conversation-search context <UUID> --json
cc-conversation-search tree <SESSION_ID> --json

Always use --json for structured output.

Examples

Example 1: Topic query

User: "Find that conversation where we fixed the authentication bug"

Todo workflow:

✓ Tool installed/upgraded
✓ Classify: TOPIC query
✓ Level 1: cc-conversation-search search "authentication bug" --days 14 --json
If no results → Level 2: cc-conversation-search search "auth bug" --json
Present results with resume commands

Example 2: Temporal query

User: "What did we work on yesterday?"

Todo workflow:

✓ Tool installed/upgraded
✓ Classify: TEMPORAL query
✓ Level 1: cc-conversation-search list --date yesterday --json
Parse conversations, group by project
Present organized summary

Example 3: Hybrid query

User: "Show me yesterday's authentication work"

Todo workflow:

✓ Tool installed/upgraded
✓ Classify: HYBRID query (topic + time)
✓ Level 1: cc-conversation-search search "authentication" --date yesterday --json
Present matching sessions

Example 4: Counting/analysis query

User: "How many times did you say 'absolutely right' in the past week?"

Todo workflow:

✓ Tool installed/upgraded
✓ Classify: HYBRID query (phrase + time)
✓ Level 1: cc-conversation-search search "absolutely right" --days 7 --json
Parse JSON, filter message_type == "assistant", count results
Present count with context snippets

Error Handling

Tool not installed:

Guide user through installation (see Prerequisites section)
Do not proceed until confirmed

Database not found:

User must run: cc-conversation-search init
Creates ~/.conversation-search/index.db

Empty results:

Follow Level 1 → 2 → 3 progression
Do not give up after Level 1
Only report "not found" after Level 3 fails

Agent Skills: Conversation Search

Skill Files