# Search History

> Search across all Claude Code conversation history (JSONL files) across all projects.

- Skill: `aviz85/search-history` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add aviz85/search-history`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aviz85/search-history/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aviz85 (https://skillmd.com/u/aviz85)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/aviz85/search-history

---


# Search Claude Code Conversation History

Search across all Claude Code sessions and projects to find past discussions, solutions, and context.

## Usage

/search-history "aviz-museum"
/search-history "supabase migration" --project Users-aviz-dreemz-backend
/search-history "Riley Brown" --user-only --limit 5

## Parameters

- `<search-term>` -- keyword or phrase to search (required)
- `--project <name>` -- limit to specific project dir (e.g., -Users-aviz-sb)
- `--user-only` -- only search user messages (skip assistant/progress/system)
- `--limit N` -- max sessions to show (default: 10)

## How It Works

### Storage Structure

```
~/.claude/projects/
  -Users-aviz-sb/                    # Project dir (path with / -> -)
    ae1972bf-...-2e6f1b34be03.jsonl   # Session file (UUID)
    ae1972bf-.../                      # Session artifacts
      subagents/                      # Subagent logs
      tool-results/                   # Tool output files
  -Users-aviz-dreemz-backend/
    ...
```

### JSONL Message Types

Each line is a JSON object with a type field:

| Type | Description | Key Fields |
|------|-------------|------------|
| `user` | User input | message.content (string or array), timestamp, cwd |
| `assistant` | Claude response | message.content (array of text/tool_use blocks), message.model |
| `progress` | Tool execution tracking | data.toolName, data.status |
| `system` | System events | Compaction, boundaries |
| `file-history-snapshot` | File backup metadata | snapshot.timestamp |
| `queue-operation` | Inbox operations | operation |
| `last-prompt` | Last user prompt text | prompt |

### Content Extraction

- **User messages:** `message.content` is usually a string, sometimes array of content blocks.
- **Assistant messages:** `message.content` is array -- extract `.text` from `type: "text"` blocks.

## Implementation

Search using grep + Python for structured output:

```bash
# Quick grep across all projects
grep -rl "SEARCH_TERM" ~/.claude/projects/*/*.jsonl
```

For structured search with context, use Python to parse JSONL files, extract matching messages, and display with session metadata (project, timestamp, message type).

## Tips

- Start broad -- grep is fast across all JSONL files
- Use `--user-only` to find what YOU asked, not what Claude replied
- Use `--project` to narrow to a specific workspace
- Session UUIDs can be used with `claude --resume SESSION_ID`
- Tool results are in separate `.txt` files under `session-dir/tool-results/`
- Subagent conversations are in `session-dir/subagents/agent-*.jsonl`