Claude History Search

Search through Claude Code conversation history to find past interactions.

🛑 Do NOT pipe to head / tail

tools claude history already bounds its own output. Piping it through head -40 / tail -20:

• truncates the result set mid-record, so a match that WAS found looks absent;
• masks the real exit code (the pipeline reports head's);
• can SIGPIPE the indexer mid-scan on --all runs.

Use the CLI's own bounds instead:

tools claude history "query" --all --limit 10             # fewer results
tools claude history "query" --all --limit 5 --context 0  # no surrounding messages
tools claude history "query" --all > /tmp/hist.md         # big result set → file, then Read it

Rules of thumb:

• Cap with --limit, never with head. Default is 20; drop to 5-10 for a scoped question.
• A quoted query on --all is rg then a parallel parse of the hits (main sessions first, then subagents). It should return in about a second, not tens of seconds. If it is still walking every JSONL, the rg prefilter failed and you will see fastPath: "rg-fallback" in the debug log.
• --summary-only reads the metadata cache: titles, summaries, and the first 5000 characters of USER text. It never sees assistant replies or tool output, so a path that only appeared in a tool result, or late in a long session, will miss. Use a normal query, or --file.
• Need only a machine answer? --format json | tools json is fine — that is a converter, not a truncator.
• Redirecting to a file with > and then Reading costs less than a re-run after a bad truncation. There is no -o flag on this command.

Quick Reference

# Basic search
tools claude history "keyword"

# Search with filters
tools claude history "query" --tool Edit --since "7 days ago"

# Interactive mode
tools claude history -i

Common Use Cases

Find by Keywords

tools claude history "backup mcp-manager refactor"
tools claude history "authentication bug" --exact

Find by File Modified

tools claude history --file "config/api.php"
tools claude history --file "*.tsx" --tool Edit
tools claude history --files ".vitrinka/" --all

--file / --files are repeatable aliases. They match tool-call file_path / path and other tool inputs (Bash command, Write content, …).

Find by Tool Usage

tools claude history --tool Edit --since "7 days ago"
tools claude history --tool Task --limit 50

Find by Project

tools claude history "timer" --project GenesisTools
tools claude history "migration" --all  # Search all projects

Show Context

tools claude history "timer" --context 10  # 10 messages before/after

CLI Options

Output Formats

Default (ai): Perfect markdown with summaries and file paths With --context: Shows surrounding messages in markdown JSON: Raw JSON for programmatic use

Performance

Content search no longer parses every JSONL under ~/.claude/projects.

1. rg -l the longest query word (or the --file token) across *.jsonl.
2. Parse those hits in parallel (16 at a time).
3. Main sessions first, then subagents, then --limit.

--exclude-agents skips the second wave. --agents-only is only wave two. A query-less --all uses the SQLite session listing (and does refresh that index). A content query does not write the index; it only reads rg + JSONL hits.

--summary-only reads the metadata cache (titles, summaries, first 5000 chars of user text). Good for names, unreliable for paths.

Summarize Sessions

Summarize Claude Code sessions using LLM-powered templates. Extracts key information and produces structured output in 7 modes.

Quick Start

# Interactive mode — guided session & mode selection
tools claude history summarize -i

# Summarize a specific session
tools claude history summarize <session-id> --mode documentation

# Summarize current session (inside Claude Code)
tools claude history summarize --current --mode short-memory

# Output prompt only (no LLM call)
tools claude history summarize <session-id> --prompt-only --mode changelog

Summarization Modes

Summarize Options

Examples

# Generate onboarding docs from a session
tools claude history summarize abc123 --mode onboarding -o docs/onboarding.md

# Extract debug learnings
tools claude history summarize abc123 --mode debug-postmortem --clipboard

# Memorization with topic files
tools claude history summarize abc123 --mode memorization --memory-dir ./memory/

# Large session with chunked processing
tools claude history summarize abc123 --mode documentation --thorough

# Custom analysis
tools claude history summarize abc123 --mode custom --custom-prompt "List all API endpoints discussed"

# Use specific model
tools claude history summarize abc123 --mode short-memory --provider anthropic --model claude-sonnet-4-5-20250929

Extract shell quirks (zsh/bash NOMATCH)

Mine Claude session JSONLs for Bash tool calls that tripped on zsh 5.9 expansion quirks (no matches found, unquoted ? in URLs, bare === equals-expansion, *(N) / nobareglobqual, for-loop aborts). Each finding includes the command, result excerpt, and exact jsonl path + line so another agent can jump straight there.

# Full report → file (notes-vault path example)
tools claude history extract-shell-quirks --all \
  -o ~/notes/claude/bugs/ZshBugs.extracted.md

# Machine JSON
tools claude history extract-shell-quirks --all --json --max 50

# One project only
tools claude history extract-shell-quirks -p GenesisTools -o /tmp/zsh.md

Dashboard

For visual exploration, tools claude history dashboard launches a web-based React/Vite interface for browsing and analyzing conversation history.