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).
/plugin marketplace add akatz-ai/cc-conversation-search/plugin install conversation-search@cc-conversation-searchThis skill is limited to using the following tools:
REFERENCE.mdFind past conversations in your Claude Code history and get the commands to resume them.
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:
Mark each todo as in_progress when starting it, completed when done.
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.
Second todo: Classify the user's query
Determine which type before executing search:
User asks about time periods WITHOUT specific topics:
Action: Use list command with date filters
User asks about CONTENT/TOPICS:
Action: Use search "topic" command
User asks about TOPIC + TIME:
Action: Use search "topic" with date filters
Execute in order. Do not skip levels.
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.
Only if Level 1 found nothing useful.
For topic/hybrid queries:
cc-conversation-search search "terms" --jsonFor temporal queries:
--days 30 instead of --days 7If matches found → skip to Level 4.
Only if Levels 1 and 2 both failed.
cc-conversation-search list --days 30 --jsoncc-conversation-search tree <SESSION_ID> --jsonFormat 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)yyyy-mm-dd, yesterday, today--days with --date/--since/--untilcc-conversation-search list --date yesterday --json
cc-conversation-search list --days 7 --json
cc-conversation-search list --since 2025-11-10 --until today --json
cc-conversation-search context <UUID> --json
cc-conversation-search tree <SESSION_ID> --json
Always use --json for structured output.
Example 1: Topic query
User: "Find that conversation where we fixed the authentication bug"
Todo workflow:
cc-conversation-search search "authentication bug" --days 14 --jsoncc-conversation-search search "auth bug" --jsonExample 2: Temporal query
User: "What did we work on yesterday?"
Todo workflow:
cc-conversation-search list --date yesterday --jsonExample 3: Hybrid query
User: "Show me yesterday's authentication work"
Todo workflow:
cc-conversation-search search "authentication" --date yesterday --jsonExample 4: Counting/analysis query
User: "How many times did you say 'absolutely right' in the past week?"
Todo workflow:
cc-conversation-search search "absolutely right" --days 7 --jsonmessage_type == "assistant", count resultsTool not installed:
Database not found:
cc-conversation-search init~/.conversation-search/index.dbEmpty results: