hist

Smart shell history. Search by intent, not syntax.

Instead of history | grep docker, ask hist search "clean up disk space" and get back the commands that actually did that -- across every session, repo, and directory you've worked in.

Features

• Semantic search -- FTS5 full-text + fuzzy matching + intent scoring
• Context-aware -- results ranked by current git repo and working directory
• Auto-tagging -- commands tagged automatically (git, docker, networking, disk, process, package, file, editor)
• Workflow detection -- finds repeated command sequences and saves them as reusable flows
• TUI browser -- interactive fzf-style interface with preview pane, exit-code colors, status footer
• Shell hooks -- zsh, bash, and fish supported
• Secret redaction -- passwords, bearer tokens, API keys masked before insert
• Import / Export -- migrate from ~/.bash_history, ~/.zsh_history, ~/.local/share/fish/fish_history; export JSON or CSV
• Delete / purge -- remove individual entries, regex matches, date ranges, or wipe everything
• Shell completions -- hist completions --shell <name>

Install

cargo install --git https://github.com/yourname/hist

Or build from source:

git clone https://github.com/yourname/hist
cd hist
cargo build --release
# copy target/release/hist to somewhere in your PATH

Note: If building on a network filesystem (NFS, CIFS), set a local build target:

CARGO_TARGET_DIR=/tmp/hist-target cargo build --release

Setup

Add to your shell config and restart your shell.

zsh (~/.zshrc):

eval "$(hist init --shell zsh)"

bash (~/.bashrc):

eval "$(hist init --shell bash)"

fish (~/.config/fish/config.fish):

hist init --shell fish | source

Usage

# Search by intent
hist search "free disk space"
hist search "kill process on port 3000"
hist search "how did I deploy"

# Filter by context
hist search "build" --repo /home/me/myproject
hist search "docker" --tag docker
hist search "build" --here          # current cwd only
hist search "build" --in-repo       # current git repo only
hist search "build" --failed        # exit code != 0
hist search "build" --exit-code 1   # exact

# Interactive TUI (fzf-like)
hist tui
hist tui "deploy"

# Add a tag manually
hist tag 42 deploy

# Delete commands
hist delete 42
hist delete --match "leaked-token"
hist delete --before 2025-12-01
hist purge --yes                    # wipe everything

# Import existing shell history
hist import --shell bash
hist import --shell zsh --file ~/.zsh_history

# Export
hist export --format json > backup.json
hist export --format csv --since 2026-01-01 > recent.csv

# Stats
hist stats
hist stats --by-hour
hist stats --by-weekday
hist stats --by-day

# Workflows
hist workflow detect
hist workflow list

# Shell completions
hist completions --shell zsh > ~/.zfunc/_hist

# Print shell hook
hist init --shell zsh

Secret redaction

Before insert, commands are run through pattern-based redaction. Built-ins cover:

• -p<password> (mysql/postgres)
• --password=..., --pass=...
• Bearer <token> in HTTP headers
• token=, api_key=, secret_key=, access_key=
• export FOO_SECRET=..., FOO_TOKEN=..., FOO_PASSWORD=...

Opt out per command: prepend a space. mysql -psecret is stored verbatim (or, with HISTCONTROL=ignorespace in your shell, not stored at all).

Opt out globally: export HIST_NO_REDACT=1.

Customize: edit ~/.config/hist/redact.toml. Each pattern is a regex with two capture groups: group 1 (kept) and group 2 (replaced with <REDACTED>).

How scoring works

Results are ranked by a combination of:

1. FTS5 BM25 full-text match score
2. Fuzzy match score (tolerates typos)
3. Tag hits from query tokens (+3 per hit)
4. Same git repo as current directory (+2)
5. Same working directory (+1)
6. Recency decay (half-life ~30 days)
7. Frequency boost (commands used more often rank higher)

Database

Stored at ~/.local/share/hist/hist.db (Linux) or ~/Library/Application Support/hist/hist.db (macOS).

Schema: commands, tags, workflows, workflow_steps, commands_fts (FTS5 virtual table).

License

MIT