abhattacherjee Conversation Search
Searches all Claude Code conversation history stored in ~/.claude/projects/. Returns matching
conversations with metadata, verbatim content, and optionally AI-generated summaries.
Quick Reference
SCRIPT=~/.claude/skills/conversation-search/scripts/search-conversations.sh
# List recent conversations
$SCRIPT list
$SCRIPT list --limit 5 --project "tiny-vacation"
# Search by topic (index-based, fast)
$SCRIPT search --topic "catalog" --after 2025-06-01
$SCRIPT search --topic "deploy" --branch "main"
# Deep search (scans JSONL content, slower)
$SCRIPT search --topic "CSRF" --deep
# Show a specific conversation (supports ID prefix)
$SCRIPT show 0be99c26
$SCRIPT show 0be99c26 --max-messages 50
# JSON output (for agent consumption)
$SCRIPT show 0be99c26 --json --max-messages 100
# Statistics
$SCRIPT stats
Workflow
Step 1: Parse the User's Query
Map natural language to script flags:
| User says | Script flags |
|---|---|
| "Find conversations about catalog maintenance" | search --topic "catalog maintenance" |
| "What did I discuss last Tuesday?" | search --after 2025-02-17 --before 2025-02-18 |
| "Show my work on the feature/story-6.5 branch" | search --branch "story-6.5" |
| "Find where I debugged CSRF errors" | search --topic "CSRF" --deep |
| "Recent conversations in tiny-vacation project" | list --project "tiny-vacation" --limit 10 |
When to use --deep: Only when the topic is unlikely to appear in the conversation's
firstPrompt or summary fields (e.g., specific error messages, function names, obscure terms).
Start without --deep first — it's much faster.
Step 2: Present Results
Run the script and present the results to the user. The script outputs formatted text by default. Show the list and ask which conversation(s) the user wants to explore further.
Step 3: Show Conversation Detail
When the user selects a conversation:
- Run
show <session-id>to display the verbatim conversation - Use
--max-messagesto control output size (default 200) - For very long conversations, start with
--max-messages 50and increase if needed
Step 4: Summarize (Optional)
If the user requests a summary, launch the conversation-summarizer agent:
Task(subagent_type="conversation-summarizer", prompt=<JSON from show --json>)
Pass the JSON output from show --json as the prompt. The agent returns a structured summary
with: key topics, decisions made, code changes, outcomes, and open items.
Tips
- Session ID prefix matching: You can use just the first 8 characters of a session ID
(e.g.,
0be99c26instead of the full UUID). - Date formats: Both
YYYY-MM-DDand full ISO 8601 are supported. - Large conversations: Some conversations have 10,000+ messages. Use
--max-messagesto avoid overwhelming output. Start with 50-100, increase if the user needs more context. - Multiple criteria: Combine filters —
search --topic "deploy" --branch "main" --after 2025-01-01 - JSON mode: Use
--jsonwhen feeding results to the summarizer agent.
See Also
context-shield— use when searching/summarizing many conversations at once; each conversation can be 10K+ messages, so distilling multiple via isolated agents avoids context overflow- GitHub: https://github.com/abhattacherjee/conversation-search — install instructions, changelog, license