HistoryGuard

Search and discover past Claude Code conversations with ease

HistoryGuard is a powerful search tool for Claude Code session history. It allows you to quickly find and reference past conversations by searching across all your session files.

Features

• 🔍 Fast Search - Search across all Claude Code session history files
• 🎯 AND Logic - Find sessions containing multiple terms simultaneously
• 📊 Rich Metadata - View session names, IDs, timestamps, working directories, and git branches
• 🚫 Deduplication - Automatically removes duplicate sessions from results
• 💡 Smart Fallbacks - Uses session summaries when available, falls back to first user message

Installation

Global Claude Code Slash Command

HistoryGuard is available as a global Claude Code slash command:

/history-search <term1> [term2] [term3] ...

The slash command is located at: ~/.claude/commands/history-search.md

Direct Shell Function

You can also source the script directly in your shell:

source /data/git/Guard8.ai/HistoryGuard/history_guard.sh

Then use the claude_search function:

claude_search <term1> [term2] [term3] ...

Usage

Search for a Single Term

/history-search authentication

Finds all sessions mentioning "authentication"

Search with Multiple Terms (AND Logic)

/history-search Docker deployment production

Finds sessions containing ALL three terms: "Docker" AND "deployment" AND "production"

More Examples

# Find React testing sessions
/history-search React testing jest

# Find database migration sessions
/history-search database migration postgres

# Find debugging sessions for a specific service
/history-search API error 500

Output Format

Each matching session displays:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Name:      Session name or summary
SessionID: unique-session-identifier
CWD:       /working/directory/path
Branch:    git-branch-name
Timestamp: 2025-10-12T19:20:00.000Z
File:      /path/to/session/file.jsonl

How It Works

1. Searches all *.jsonl files in ~/.claude/projects/
2. Filters using grep with AND logic (all terms must be present)
3. Extracts metadata using jq JSON parser
4. Deduplicates sessions using bash associative arrays
5. Displays formatted results with visual separators

Requirements

• bash 4.0+ (for associative arrays)
• grep (with -r and -l flags)
• jq (JSON processor)
• Claude Code session history files

Technical Details

Search Algorithm

• Uses grep -rl for efficient file-level searching
• Chains multiple grep -l calls for AND logic
• Process substitution prevents subshell variable scope issues
• Associative array ensures unique session IDs

Session Name Priority

1. Session summary from "type":"summary" field
2. First user message truncated to 60 characters
3. "(unnamed session)" as fallback

File Locations

• History Files: ~/.claude/projects/**/*.jsonl
• Script: /data/git/Guard8.ai/HistoryGuard/history_guard.sh
• Slash Command: ~/.claude/commands/history-search.md

Testing

The script includes comprehensive tests:

# Test syntax
bash -n history_guard.sh

# Test function loading
source history_guard.sh && type claude_search

# Test error handling
claude_search  # Should show usage message

# Test single search
claude_search "test"

# Test multiple terms
claude_search "term1" "term2"

All tests pass successfully ✅

Integration with Guard8.ai

HistoryGuard is part of the Guard8.ai security toolkit ecosystem:

• HalluciGuard - AI hallucination detection
• ContextGuard - Context security monitoring
• HistoryGuard - Session history search (this project)

Contributing

Improvements and suggestions are welcome! Please ensure:

• Bash compatibility (4.0+)
• Error handling for missing dependencies
• Clear usage messages
• Proper quoting for shell safety

License

Part of the Guard8.ai project

Author

Created for efficient Claude Code session history management

---

Quick Start: Run /history-search <your-search-term> in Claude Code to get started!