# Conversation Search > Find and resume Claude Code conversations by searching topics or filtering by date. Returns session IDs and project paths for easy resumption via 'claude --resume'. Use when user asks "find that conversation about X", "what did we discuss", "what did we work on yesterday", "summarize today's work", "show this week's conversations", "recent projects we accomplished", or wants to locate past work by topic, date, or time period (yesterday, today, last week, specific dates). - Skill: `amitkot/conversation-search` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add amitkot/conversation-search` - Raw SKILL.md: https://api.skillmd.com/api/skills/amitkot/conversation-search/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: amitkot (https://skillmd.com/u/amitkot) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/amitkot/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. ```bash 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: ```bash 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: (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: ```bash # 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: ```bash 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 --json`. 4. Read message summaries to locate content. ### Level 4 — present results Format for the user: ```markdown **Session Details** - **Session**: - **Project**: - **Time**: - **Message**: (if applicable) **To resume** ```bash cd claude --resume ``` ``` 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) ```bash 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 ```bash cc-conversation-search context --json cc-conversation-search tree --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`](https://github.com/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.