GitHub - jondot/bhgrep: like ripgrep but for browser history

6 min read Original article ↗

bhgrep 🔍

Fuzzy search over your local browser history across all browsers

CI License: MIT Rust Crates.io

bhgrep is a blazing-fast command-line tool that lets you search through your browser history across Chrome, Firefox, Safari, and Edge with fuzzy matching, regex support, and an interactive TUI.

✨ Features

  • 🔍 Fuzzy Search - Find pages even with typos or partial matches
  • 🎯 Regex Support - Powerful pattern matching for advanced queries
  • 🖥️ Interactive TUI - Beautiful terminal interface for browsing results
  • 📋 CLI Mode - Script-friendly output with JSON, plain text, or URL-only formats
  • 🌐 Multi-Browser - Automatically searches Chrome, Firefox, Safari, and Edge
  • ⚡ Smart Scoring - Prioritizes recent and frequently visited pages
  • 🔗 Quick Actions - Open URLs or copy to clipboard with a single keystroke
  • 🚀 Fast - Efficient indexing and caching for instant results

📦 Installation

From Source

git clone https://github.com/jondot/bhgrep.git
cd bhgrep
cargo build --release

The binary will be at target/release/bhgrep. You can add it to your PATH:

sudo cp target/release/bhgrep /usr/local/bin/

Using Cargo

🚀 Quick Start

Interactive Mode (Default)

Simply run bhgrep without arguments to enter interactive mode:

Keyboard shortcuts:

  • Type to search
  • Enter: Open selected URL in browser
  • y: Copy URL to clipboard
  • Esc or q: Quit
  • ↑/↓: Navigate results
  • Ctrl+U: Clear search

CLI Mode

Search with a query:

bhgrep --query "rust programming"

📖 Usage

Basic Examples

# Search and output as JSON
bhgrep -q "rust" --format json

# Get only URLs (perfect for scripting)
bhgrep -q "tutorial" --format url-only

# Open first result in browser
bhgrep -q "github" --open

# Copy first result URL to clipboard
bhgrep -q "stackoverflow" --copy

# Search only Chrome history
bhgrep -q "documentation" --browser chrome

# Use regex for pattern matching
bhgrep --mode regex -q "github\.com/.*/.*" --format url-only

Advanced Examples

# Find all GitHub repos you've visited
bhgrep -q "github.com" --format url-only | grep -E "github\.com/[^/]+/[^/]+" | sort -u

# Export full history as JSON for analysis
bhgrep -q "" --format json --limit 10000 > history.json

# Search with custom limit
bhgrep -q "documentation" --limit 50

# Use database mode for faster startup (slower queries)
bhgrep -q "search term" --mode db

Output Formats

  • plain (default): Human-readable format with title, URL, and metadata
  • json: JSON format perfect for scripting and automation
  • url-only: Just URLs, one per line

🎯 Use Cases

For Developers

# Quick alias for documentation lookup
alias doc='bhgrep -q "$1" --format url-only --open'

# Find all Stack Overflow answers you've visited
bhgrep -q "stackoverflow.com" --format url-only

# Collect resources for a project
bhgrep -q "myproject" --format json | jq '.[] | .url' > resources.txt

For Security Researchers

# Export sensitive history for analysis
bhgrep -q "token=" --format json --limit 50000 > full_history.json

# Find visits to specific domains
bhgrep --mode regex -q "example\.com" --format json

# Timeline analysis
bhgrep -q "target" --format json | jq -r '.[] | "\(.last_visit) | \(.url)"' | sort

🌐 Supported Browsers

  • ✅ Google Chrome - Full support
  • ✅ Mozilla Firefox - Full support
  • ✅ Safari - Full support (macOS only)
  • ✅ Microsoft Edge - Full support

The tool automatically detects available browsers and searches across all of them.

🔧 Command-Line Options

USAGE:
    bhgrep [OPTIONS]

OPTIONS:
    -q, --query <QUERY>        Search query (enables non-interactive mode)
    -n, --limit <LIMIT>        Limit number of results [default: 10]
    --format <FORMAT>           Output format: plain, json, or url-only [default: plain]
    --open                      Open first result in browser
    --copy                      Copy first result URL to clipboard
    --browser <BROWSER>         Filter by browser: chrome, firefox, safari, or edge
    --mode <MODE>               Search mode: fuzzy, db, or regex [default: fuzzy]
    --cache-freshness <SECS>    Cache freshness in seconds [default: 600]
    -h, --help                  Print help information
    -V, --version               Print version information

Search Modes

  • fuzzy (default): Loads all history to memory, then performs fast fuzzy search
  • db: Queries database directly on each search (faster startup, slower queries)
  • regex: Loads all history to memory, then performs regex pattern matching

🏗️ Building from Source

Prerequisites

  • Rust 1.70 or later
  • Cargo

Build

# Debug build
cargo build

# Release build (optimized)
cargo build --release

Run Tests

Run Linter

cargo clippy --all-targets --all-features -- -D warnings

Check Formatting

cargo fmt --all -- --check

📁 Project Structure

bhgrep/
├── src/
│   ├── browsers/          # Browser-specific history readers
│   │   ├── chrome.rs
│   │   ├── firefox.rs
│   │   ├── safari.rs
│   │   └── edge.rs
│   ├── search.rs          # Search algorithms (fuzzy, regex)
│   ├── scoring.rs         # Scoring and ranking logic
│   ├── tui.rs            # Terminal UI
│   ├── output.rs         # Output formatting
│   └── main.rs           # CLI entry point
├── .github/
│   └── workflows/
│       └── ci.yml        # CI/CD pipeline
└── Cargo.toml

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/jondot/bhgrep.git
cd bhgrep

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- -q "test"

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

📊 Performance

bhgrep is optimized for speed:

  • Fuzzy mode: Fast queries after initial load (~100ms for 10k entries)
  • DB mode: Fast startup, queries database directly
  • Smart caching: Browser databases are cached to avoid repeated file operations
  • Efficient scoring: Only clones entries that make it to final results

🐛 Troubleshooting

No results found

  • Make sure you have browser history in supported browsers
  • Try a broader search query
  • Check that browsers are installed and have history

Permission errors (macOS)

  • Grant Full Disk Access to Terminal/iTerm in System Preferences
  • Safari requires Full Disk Access to read its history database

Slow performance

  • Use --mode db for faster startup if you have large history
  • Reduce --limit for faster results
  • Consider using --browser to search only specific browsers

🔗 Related Projects

Made with ❤️ by @jondot

If you find bhgrep useful, please consider giving it a ⭐ on GitHub!