conversation-search

Conversation Search

Find past conversations in your Claude Code history and get the commands to resume them. Drives the upstream cc-conversation-search CLI against a local SQLite FTS5 index at ~/.conversation-search/index.db.

Preflight: CLI must already be installed

This skill assumes cc-conversation-search is on $PATH. If it isn't, stop and tell the user:

The conversation-search CLI isn't installed. Run /conversation-search-setup
(or ask me to "set up conversation search") to install it, then try again.

Do not attempt to install it from this skill — installs belong in the conversation-search-setup sibling skill so the search hot path stays fast.

command -v cc-conversation-search >/dev/null 2>&1 || { echo "CLI missing — run setup skill first"; exit 0; }

CRITICAL: Quote hyphenated queries

The upstream CLI (v0.5.3) passes the query string straight into SQLite FTS5. A bare hyphen breaks the parser:

cc-conversation-search search "conversation-search plugin"   # → Error: no such column: search
cc-conversation-search search '"conversation-search plugin"' # → works

Rule: any query containing - or other punctuation must be wrapped in inner double quotes (so the shell sends "conversation-search plugin" to the CLI). Plain space-separated words don't need it.

In practice: when in doubt, quote. It's safe for single words too.

Tracked upstream: https://github.com/akatz-ai/cc-conversation-search/issues (file one if missing).

MANDATORY FIRST STEP — CREATE TODO CHECKLIST

Before doing anything else, use TodoWrite to create this checklist:

- 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

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 for all search operations.

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

Query Type Classification

Type 1: Temporal — time period, no specific topic

Examples:

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

Action: cc-conversation-search list with date filters.

Type 2: Topic — content / topic, no time scope

Examples:

• "Find that Redis conversation"
• "Where did we discuss authentication?"

Action: cc-conversation-search search "query".

Type 3: Hybrid — topic + time

Examples:

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

Action: cc-conversation-search search "query" with date filters.

Three-Level Search Workflow

Execute in order. Do not skip levels.

Level 1 — focused search (ALWAYS START HERE)

Topic / hybrid:

# Plain words — no inner quotes needed
cc-conversation-search search "search terms" --days 14 --json

# Hyphenated or punctuation-containing — inner quotes mandatory (see CRITICAL section)
cc-conversation-search search '"conversation-search plugin"' --days 14 --json

Temporal:

cc-conversation-search list --date yesterday --json
# or: --days N, --since YYYY-MM-DD, --until YYYY-MM-DD

Parse the JSON. If you find relevant matches, skip to Level 4.

Search auto-indexes recent conversations before running, so the result is fresh.

Level 2 — broader search

Only if Level 1 found nothing useful.

Topic / hybrid:

• Drop the time constraint: cc-conversation-search search "terms" --json.
• Try alternative keywords: auth vs authentication, db vs postgres.

Temporal:

• Expand: --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.

1. cc-conversation-search list --days 30 --json
2. Review conversation summaries.
3. For promising sessions: cc-conversation-search tree <SESSION_ID> --json.
4. Read message summaries to locate content.

Level 4 — present results

Format for the user:

**Session Details**
- **Session**: <session-id>
- **Project**: <project-path>
- **Time**: <YYYY-MM-DD HH:MM>
- **Message**: <message-uuid> (if applicable)

**To resume**
```bash
cd <project-path>
claude --resume <session-id>

For counting / analysis queries:
- Parse JSON.
- Filter by `message_type` if needed (`user` vs `assistant`).
- Count matches, present with evidence snippets.

If nothing found after all three levels:
- Tell the user: "No matching conversations found after exhaustive search."
- Suggest: `cc-conversation-search index --days 90` to reindex older history.
- Note that the conversation may predate the indexed range.

## Command quick-reference

### Search (topic / hybrid)
```bash
cc-conversation-search search "query" --days N --json
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
cc-conversation-search search "query" --json      # all time

Date filter options:

• --days N — last N days from now.
• --date DATE — specific calendar day.
• --since DATE / --until DATE — inclusive range.
• DATE formats: YYYY-MM-DD, yesterday, today.
• Cannot mix --days with --date/--since/--until.

List (temporal)

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 <message-uuid> --json
cc-conversation-search tree <session-id> --json

Always pass --json for structured output.

Full flag reference: REFERENCE.md in this skill directory.

Examples

Topic query — "Find that conversation where we fixed the authentication bug"

1. Classify: TOPIC.
2. Level 1: cc-conversation-search search "authentication bug" --days 14 --json.
3. If empty, Level 2: cc-conversation-search search "auth bug" --json.
4. Present results.

Temporal query — "What did we work on yesterday?"

1. Classify: TEMPORAL.
2. Level 1: cc-conversation-search list --date yesterday --json.
3. Group by project, present organised summary.

Hybrid — "Show me yesterday's authentication work"

1. Classify: HYBRID.
2. Level 1: cc-conversation-search search "authentication" --date yesterday --json.

Counting — "How many times did you say 'absolutely right' in the past week?"

1. Classify: HYBRID (phrase + time).
2. cc-conversation-search search "absolutely right" --days 7 --json.
3. Filter message_type == "assistant", count.

Error handling

• cc-conversation-search: command not found — point at /conversation-search-setup. Do not silently install.
• Database not found — same: run setup.
• Empty results — keep going through Level 1 → 2 → 3 before reporting "not found".

Upstream

Adapted from akatz-ai/cc-conversation-search (MIT). The Python CLI is upstream's; this skill is the workflow wrapper. Install/upgrade is delegated to the conversation-search-setup sibling skill.