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:
- -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