Conversation Search

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 to display the verbatim conversation
• Use --max-messages to control output size (default 200)
• For very long conversations, start with --max-messages 50 and increase if needed

Step 4: Summarize (Optional)

If the user requests a summary, launch the conversation-summarizer agent:

Task(subagent_type="conversation-summarizer", prompt=)

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., 0be99c26 instead of the full UUID).

• Date formats: Both YYYY-MM-DD and full ISO 8601 are supported.
• Large conversations: Some conversations have 10,000+ messages. Use --max-messages

to 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 --json when 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abhattacherjee
• Source: abhattacherjee/claude-code-skills
• License: MIT

Install and usage instructions live in the source repository linked above.