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.

⭐6stars🔀1forks📁View on GitHub🕐Updated Dec 20, 2025⬇️2downloads

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.
namerg_history
descriptionSearch 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:

  • -c to count matches
  • -o '.{0,60}pattern.{0,60}' for snippets
  • -M 200 to truncate lines
  • | head -20 to 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'