bhgrep

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 30 Open GitHub ↗

like ripgrep but for browser history

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# bhgrep 🔍

> **Fuzzy search over your local browser history across all browsers**

[![CI](https://github.com/jondot/bhgrep/workflows/CI/badge.svg)](https://github.com/jondot/bhgrep/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)
[![Crates.io](https://img.shields.io/crates/v/bhgrep.svg)](https://crates.io/crates/bhgrep)

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

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

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

### Using Cargo

```bash
cargo install bhgrep
```

## 🚀 Quick Start

### Interactive Mode (Default)

Simply run `bhgrep` without arguments to enter interactive mode:

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

```bash
bhgrep --query "rust programming"
```

## 📖 Usage

### Basic Examples

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Debug build
cargo build

# Release build (optimized)
cargo build --release
```

### Run Tests

```bash
cargo test
```

### Run Linter

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

### Check Formatting

```bash
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

```bash
# 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](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Rust](https://www.rust-lang.org/)
- Uses [ratatui](https://github.com/ratatui-org/ratatui) for the TUI
- Uses [fuzzy-matcher](https://github.com/lotabout/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](https://github.com/junegunn/fzf) - A command-line fuzzy finder
- [ripgrep](https://github.com/BurntSushi/ripgrep) - A line-oriented search tool
- [browser-history](https://github.com/pesos/browser-history) - Python browser history tool

---

**Made with ❤️ by [@jondot](https://github.com/jondot)**

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

bhgrep

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README