| name | session-search |
| description | Search previous Claude Code session history by keyword. Use when the user asks to find a past conversation, recall what was discussed, or locate a session where a topic came up. |
Session Search
Search across all Claude Code session transcripts (every ~/.claude*/ config dir — .claude, .claude-ant, etc. — plus ~/.agents/) and Pi agent sessions (~/.pi/agent/sessions/), including Pi artifacts (plans, context docs, etc.).
When to use
- User asks "which session did we talk about X?"
- User wants to find a previous conversation by topic
- User needs to recall advice, code, or decisions from past sessions
Usage
Run the helper script with a quoted search query:
python3 ~/.claude/skills/session-search/scripts/search.py "your search terms"
All terms must appear in the same text block for a match (AND logic).
Options
| Flag | Default | Purpose |
|---|
--project <str> | all | Filter to project dirs containing this string |
--context <n> | 200 | Characters of context around each match |
--limit <n> | 10 | Max sessions to display |
Examples
python3 ~/.claude/skills/session-search/scripts/search.py "margin notes"
python3 ~/.claude/skills/session-search/scripts/search.py "LoRA" --project kb
python3 ~/.claude/skills/session-search/scripts/search.py "deploy" --context 400 --limit 20
Output
For each matching session the script prints:
- Session ID and resume command (
claude::resume <id> — cd's into the session's original directory and resumes via the owning config profile; defined in modules/claude/aliases.zsh)
- Date, project, and the original prompt
- Up to 3 matching snippets with role labels and line numbers
Notes
- Searches
~/.claude*/projects/ (all config-dir variants), ~/.agents/projects/, and ~/.pi/agent/sessions/ for session transcripts
- History index from every
~/.claude*/history.jsonl plus ~/.agents/history.jsonl
- Pi sessions are identified with
[pi] label and resume via pi::resume <id> (cd's into the session's directory, then pi --session <id>; defined in modules/pi/aliases.zsh)
- Pi artifacts (markdown files under
artifacts/) are also searched and labelled (pi artifact: <name>)
- Searches text content from user and assistant messages (skips tool calls, binary data, etc.)
- Subagent files are not searched (only top-level session files)
