hstr — Interactive Shell History Search with Suggestions

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