# hstr — Interactive Shell History Search with Suggestions

> A C-based tool that replaces the default Ctrl-R reverse search with a visual, filterable history browser supporting favorites and frequency-ranked results.

## Install

Save in your project root:

# hstr — Interactive Shell History Search with Suggestions

## Quick Use
```bash
# Install
brew install hstr           # macOS
sudo apt install hstr       # Debian/Ubuntu

# Configure (add to ~/.bashrc or ~/.zshrc)
hstr --show-configuration >> ~/.bashrc
source ~/.bashrc

# Use: press Ctrl-R to launch hstr instead of default reverse search
```

## Introduction
hstr (originally hh) is a shell history browser that replaces the default Ctrl-R reverse-search with a full-screen interactive interface. It ranks commands by frequency, recency, and length, and lets you bookmark frequently used commands for quick access.

## What hstr Does
- Displays shell history in a scrollable, searchable full-screen interface
- Ranks commands using a combination of frequency, recency, and length metrics
- Supports three view modes: ranked, chronological, and favorites
- Allows bookmarking commands as favorites for instant recall
- Removes duplicate and blacklisted entries to keep history clean

## Architecture Overview
hstr is written in C and reads directly from the shell's history file (~/.bash_history or equivalent). It builds an in-memory index of commands, scores them using a weighted ranking algorithm, and renders the UI using ncurses. The favorites list is stored in ~/.hstr_favorites. hstr hooks into the shell by binding to Ctrl-R via a shell function.

## Self-Hosting & Configuration
- Install via Homebrew, apt, pacman, or build from source with make
- Run ``hstr --show-configuration`` to generate the shell integration snippet
- Configure the HSTR_CONFIG environment variable to set sorting, colors, and blacklist
- Favorites are stored in ~/.hstr_favorites as a plain text file
- Blacklisted commands (e.g., passwords) can be excluded from history display

## Key Features
- Three display modes: ranked by frequency, raw chronological order, and favorites
- Substring and regex search within history entries
- Delete individual history entries from within the interface
- Case-insensitive search by default with optional case-sensitive mode
- Minimal resource usage with instant startup time

## Comparison with Similar Tools
- **fzf + Ctrl-R** — fzf provides fuzzy history search but requires shell integration setup; hstr is purpose-built for history
- **Atuin** — syncs history across machines with SQLite and encryption; hstr is local-only and simpler
- **McFly** — uses a neural network for ranking; hstr uses a simpler frequency/recency algorithm
- **zsh-autosuggestions** — inline suggestions while typing; hstr is an interactive full-screen browser
- **bash built-in Ctrl-R** — basic reverse search one result at a time; hstr shows all matches at once

## FAQ
**Q: Does hstr modify my shell history file?**
A: hstr reads the history file but does not modify it automatically. You can delete individual entries from within hstr, which updates the history.

**Q: Does it work with zsh?**
A: Yes. hstr supports both bash and zsh, with configuration snippets for each shell.

**Q: What does the ranking algorithm consider?**
A: Commands are scored based on how often they appear (frequency), how recently they were used (recency), and command length (shorter commands rank slightly higher for common operations).

**Q: Can I sync favorites across machines?**
A: The favorites file is a plain text file at ~/.hstr_favorites. You can sync it using dotfile managers or cloud storage.

## Sources
- https://github.com/dvorka/hstr
- https://github.com/dvorka/hstr/blob/master/CONFIGURATION.md

---
Source: https://tokrepo.com/en/workflows/asset-c09bc9e9
Author: AI Open Source