How do I install the Search Chats skill?

Run npx skillmds@latest add benjaminshoemaker/search-chats 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.

Is Search Chats safe to use?

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

Which AI agents work with Search Chats?

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 Chats free to use?

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

Who published Search Chats?

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

Search Chats by benjaminshoemaker — Agent Skill

Name: Search Chats
Author: benjaminshoemaker

Search Chats

Search past conversations with Claude Code and Codex CLI. Finds matching excerpts across all sessions with metadata (date, project, agent). Use when looking for a past discussion, decision, or piece of context from any previous session.

File contents

Search past conversation transcripts across Claude Code and Codex CLI sessions.

@shared/SESSION_PARSING.md

Arguments

Parse the user's input for:

query (required) — the search terms
--agent claude|codex — restrict to one agent (default: both)
--project <name> — filter to sessions whose project path contains this string
--days <N> — only search sessions modified in the last N days (default: 30)

Workflow

1. Discover Session Files

Use Bash to find JSONL files, filtered by recency:

# Claude Code sessions
find ~/.claude/projects -name "*.jsonl" -not -path "*/subagents/*" -mtime -${DAYS} -type f

# Codex CLI sessions
find ~/.codex/sessions -name "*.jsonl" -mtime -${DAYS} -type f

If --project is set, pipe through grep -i "<project>" to filter paths. If --agent is set, skip the other source entirely.

2. Search Each File

For each session file, use Bash with grep -i to check if the query appears before reading the full file. Only parse files that match.

For matched files, read and extract:

Session metadata: project path, date, agent (claude/codex), session ID
Matching turns: the user or assistant message containing the query
Surrounding context: the immediately preceding and following turns

3. Extract Metadata

Claude Code files:

Project: decode directory name (e.g., -Users-ben-shoemaker-Projects-myapp → myapp)
Date: timestamp field from first user event, or file mtime
Agent: claude

Codex CLI files:

Project: session_meta.payload.cwd basename
Date: from filename timestamp pattern rollout-YYYY-MM-DDTHH-MM-SS-...
Agent: codex

4. Present Results

Sort results by date (newest first). For each match:

## [DATE] PROJECT (AGENT)
Session: SESSION_ID

> **User:** [matching user message excerpt]
> **Assistant:** [matching assistant response excerpt]

---

Truncate long messages to ~300 chars with ... continuation marker.

If no results found:

No matches for "QUERY" in the last DAYS days.
Try broadening the search: fewer keywords, more days (--days 90), or drop the project filter.

5. Summary

End with a one-line count: Found N matches across M sessions.

---name: search-chatsdescription: Search past conversations with Claude Code and Codex CLI. Finds matching excerpts across all sessions with metadata (date, project, agent). Use when looking for a past discussion, decision, or piece of context from any previous session.---Search past conversation transcripts across Claude Code and Codex CLI sessions.@shared/SESSION_PARSING.md## ArgumentsParse the user's input for:- **query** (required) — the search terms- `--agent claude|codex` — restrict to one agent (default: both)- `--project <name>` — filter to sessions whose project path contains this string- `--days <N>` — only search sessions modified in the last N days (default: 30)## Workflow### 1. Discover Session FilesUse Bash to find JSONL files, filtered by recency:```bash# Claude Code sessionsfind ~/.claude/projects -name "*.jsonl" -not -path "*/subagents/*" -mtime -${DAYS} -type f# Codex CLI sessionsfind ~/.codex/sessions -name "*.jsonl" -mtime -${DAYS} -type f```If `--project` is set, pipe through `grep -i "<project>"` to filter paths.If `--agent` is set, skip the other source entirely.### 2. Search Each FileFor each session file, use Bash with `grep -i` to check if the query appears before reading the full file.Only parse files that match.For matched files, read and extract:- **Session metadata**: project path, date, agent (claude/codex), session ID- **Matching turns**: the user or assistant message containing the query- **Surrounding context**: the immediately preceding and following turns### 3. Extract Metadata**Claude Code files:**- Project: decode directory name (e.g., `-Users-ben-shoemaker-Projects-myapp` → `myapp`)- Date: `timestamp` field from first user event, or file mtime- Agent: `claude`**Codex CLI files:**- Project: `session_meta.payload.cwd` basename- Date: from filename timestamp pattern `rollout-YYYY-MM-DDTHH-MM-SS-...`- Agent: `codex`### 4. Present ResultsSort results by date (newest first). For each match:```## [DATE] PROJECT (AGENT)Session: SESSION_ID> **User:** [matching user message excerpt]> **Assistant:** [matching assistant response excerpt]---```Truncate long messages to ~300 chars with `...` continuation marker.If no results found:```No matches for "QUERY" in the last DAYS days.Try broadening the search: fewer keywords, more days (--days 90), or drop the project filter.```### 5. SummaryEnd with a one-line count: `Found N matches across M sessions.`

Frequently asked questions