bhgrep 🔍

Fuzzy search over your local browser history across all browsers

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

cargo install bhgrep

🚀 Quick Start

Interactive Mode (Default)

Simply run bhgrep without arguments to enter interactive mode:

bhgrep

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

cargo test

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

• Built with Rust
• Uses ratatui for the TUI
• Uses fuzzy-matcher for fuzzy search
• Inspired by tools like fzf and ripgrep

📊 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

• fzf - A command-line fuzzy finder
• ripgrep - A line-oriented search tool
• browser-history - Python browser history tool

---

Made with ❤️ by @jondot

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