search-history
Search Claude conversation history from JSONL files. Use when looking for previous discussions, past decisions, code solutions, or context from earlier conversations.
When & Why to Use This Skill
The search-history Claude skill enables efficient retrieval of past conversation data from local JSONL files. It empowers users and agents to locate previous technical decisions, code implementations, and historical context without consuming tokens during the search process, significantly enhancing the continuity and intelligence of long-term development workflows.
Use Cases
- Case 1: Retrieving specific architectural decisions or logic explanations from previous chat sessions to ensure consistency in ongoing software projects.
- Case 2: Locating and reusing code solutions or bug fixes implemented in earlier conversations to avoid redundant effort and improve productivity.
- Case 3: Gathering historical context for complex tasks where past discussions provide essential background information for current problem-solving.
- Case 4: Auditing project evolution by searching and filtering through session metadata to track the progress of specific features or milestones.
| name | search-history |
|---|---|
| description | Search Claude conversation history from JSONL files. Use when looking for previous discussions, past decisions, code solutions, or context from earlier conversations. |
| allowed-tools | Bash, Read |
Conversation History Search
Search through Claude Code conversation history to find relevant past discussions.
When to Use
- Finding previous discussions about a topic
- Recalling past decisions or solutions
- Getting context from earlier conversations
- Looking up how something was implemented before
How to Search
Run the search script from the services directory:
cd ~/.claude/services
python conversation-search.py "search term"
Search Options
| Option | Description |
|---|---|
--list-sessions, -l |
List all sessions with metadata |
--session ID, -s |
Filter to specific session (partial match) |
--context N, -c |
Show N messages before/after (default: 3) |
--max N, -m |
Maximum results (default: 20) |
--verbose, -v |
Show context messages |
--full, -f |
Show full message content |
Examples
# List all available sessions
python conversation-search.py --list-sessions
# Basic search
python conversation-search.py "bulk upload"
# Regex search
python conversation-search.py "context.*percent|usage.*%"
# Search specific session with full output
python conversation-search.py "statusline" --session 6cabef43 --full
# Get more context around matches
python conversation-search.py "error" --context 5 --verbose --max 3
Output Modes
- Default: Preview snippet (50 chars before, 100 after match)
- Verbose (
-v): Adds surrounding message context - Full (
-f): Complete message content
Token Efficiency
The search runs externally, so searching costs 0 tokens. Only the returned results consume context.