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:

# 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