How do I install the Search History skill?

Run npx skillmds@latest add aviz85/search-history in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Search History skill do?

Search across all Claude Code conversation history (JSONL files) across all projects. It is listed under Coding & Dev Tools on SkillMD.

Is Search History safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Search History?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Search History free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Search History?

aviz85 (@aviz85) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Search History by aviz85 — Agent Skill

Name: Search History
Rating: 4.2 (5 reviews)
Author: aviz85

File contents

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

---name: search-historydescription: Search across all Claude Code conversation history (JSONL files) across all projects.--- # 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`

Frequently asked questions

Search History