# Conversation Search

> Searches Claude Code conversation history in ~/.claude/projects/ by topic, date, branch, or project. Provides verbatim conversation content and AI-generated summaries. Use when: (1) user asks to find a past conversation, (2) user wants to recall what was discussed on a topic or date, (3) user asks to search conversation history, (4) /conversation-search command.

- **Type:** Skill
- **Install:** `agentstack add skill-abhattacherjee-claude-code-skills-conversation-search`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [abhattacherjee](https://agentstack.voostack.com/s/abhattacherjee)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [abhattacherjee](https://github.com/abhattacherjee)
- **Source:** https://github.com/abhattacherjee/claude-code-skills/tree/main/conversation-search

## Install

```sh
agentstack add skill-abhattacherjee-claude-code-skills-conversation-search
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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](https://github.com/abhattacherjee)
- **Source:** [abhattacherjee/claude-code-skills](https://github.com/abhattacherjee/claude-code-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-abhattacherjee-claude-code-skills-conversation-search
- Seller: https://agentstack.voostack.com/s/abhattacherjee
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.