rg-history
Search your conversation history using ripgrep. Use when you need to find previous messages, file edits, tool calls, or decisions from earlier in the session.
When & Why to Use This Skill
The rg_history Claude skill provides a high-performance search interface for conversation history using ripgrep. It enables agents to efficiently query session logs (JSONL) to retrieve previous messages, file edits, tool invocations, and reasoning steps. By implementing optimized search strategies like snippet extraction and match counting, it prevents context overflow while ensuring the agent maintains a perfect memory of past decisions and actions throughout complex, long-running workflows.
Use Cases
- Tracking Code Evolution: Search for specific 'Edit' or 'Write' tool calls to understand when and why a particular block of code was modified during the session.
- Retrieving Past Decisions: Quickly locate 'thinking' blocks or user instructions from earlier in the conversation to ensure current actions align with previously established goals.
- Debugging Multi-Agent Interactions: Trace the activity of sub-agents by searching through agent-specific JSONL files to identify where a delegated task might have deviated.
- Auditing Tool Outputs: Use ripgrep patterns to find the results of previous bash commands or API calls without scrolling through thousands of lines of session history.
- Context Recovery in Long Sessions: Summarize previous interactions by extracting snippets of human input and assistant responses to maintain continuity in complex projects.
| name | rg_history |
|---|---|
| description | Search your conversation history using ripgrep. Use when you need to find previous messages, file edits, tool calls, or decisions from earlier in the session. |
rg_history
Search your session history with ripgrep.
CRITICAL: Search Strategy
Each event is one long JSON line. Full output will overwhelm you. Always start broad with limited output, then narrow in.
The Pattern
# 1. COUNT first - how many matches?
rg -c 'search_term' session.jsonl
# 2. SNIPPETS - get context around matches (not full lines)
rg -o '.{0,60}search_term.{0,60}' session.jsonl | head -20
# 3. NARROW - pipe to filter further
rg -o '.{0,60}search_term.{0,60}' session.jsonl | rg 'new_string'
# 4. FULL CONTEXT - only when you know what you want
rg '"name":"Edit".*search_term' session.jsonl -M 500
Never run raw rg 'pattern' file.jsonl - you'll get walls of JSON.
Always use one of:
-cto count matches-o '.{0,60}pattern.{0,60}'for snippets-M 200to truncate lines| head -20to limit results
Find Your Session Files
Run the helper script:
scripts/list-sessions.sh /path/to/project # defaults to cwd
Or construct manually:
~/.claude/projects/{encoded_project_path}/{session_id}.jsonl
Where encoded_project_path = project path with / replaced by -.
File Structure
~/.claude/projects/-Users-ramos-my-project/
├── abc123-def4-5678-....jsonl # Main session (UUID format)
├── agent-a1b2c3d.jsonl # Sub-agent spawned by Task tool
└── ...
- Main session: Full UUID, your conversation
- Agent files:
agent-{7-char-id}.jsonl, from Task tool - Agent IDs appear in results as
"agentId": "a1b2c3d"
JSONL Structure Reference
Each line is one JSON object. Key fields:
Message types:
"type":"user"+"userType":"external"= actual human input"type":"assistant"= Claude's responses"type":"tool_result"= tool output
Tool calls (in assistant messages):
"name":"Edit"→"input":{"file_path":"...", "old_string":"...", "new_string":"..."}"name":"Write"→"input":{"file_path":"...", "content":"..."}"name":"Bash"→"input":{"command":"..."}"name":"Task"→"input":{"prompt":"...", "subagent_type":"..."}
Content blocks:
"type":"text"- message text"type":"thinking"- Claude's reasoning"type":"tool_use"- tool invocation
Other fields:
"timestamp":"2025-12-20T..."- when it happened"agentId":"..."- links to agent file"isCompactSummary":true- compacted context
Example Search Patterns
Remember: always use snippets or limit output!
# Find human messages (not tool results)
rg -o '.{0,40}"userType":"external".{0,40}' session.jsonl | head -10
# Find file edits
rg -c '"name":"Edit"' session.jsonl # count first
rg -o '.{0,50}"name":"Edit".{0,50}' session.jsonl | head -10
# Find edits to specific file
rg -o '.{0,30}auth.{0,30}' session.jsonl | rg 'file_path'
# Find commands that were run
rg -o '.{0,80}"command":".{0,80}' session.jsonl | head -10
# Find code in file writes
rg -o '.{0,60}function.{0,60}' session.jsonl | rg 'new_string\|content'
Quick Reference
| Goal | Command |
|---|---|
| Count matches | rg -c 'pattern' file |
| Snippets | rg -o '.{0,60}pattern.{0,60}' file |
| Limit output | | head -20 |
| Truncate lines | -M 200 |
| Case insensitive | -i |
| Chain filters | rg 'a' | rg 'b' |