zsh-histdb: SQLite history with richer command metadata

What zsh-histdb records beyond the command text

zsh-histdb addresses a specific limitation in zsh's normal history mechanism: the default history file primarily tells you which commands were entered, but it does not preserve a queryable record of several properties engineers often need. According to the README, the project stores each command's start and stop times, working directory, hostname, per-host session ID, and exit status.

This is aimed at users who move among multiple shells or machines and later need to reconstruct where a command ran and how it ended. A search for `strace`, for example, can show commands from several sessions and distinguish entries with the same session number. Directory, host, session, and time filters are available through `histdb --help`.

The storage model also supports merging history databases from multiple machines without conflict, provided the machines use different hostnames. That condition matters. Reusing a hostname can undermine the intended identity separation because the session identifier is unique per host rather than globally unique across every system.

The SQLite recording and query path

The repository is centered on `sqlite-history.zsh`, which must be sourced from the zsh startup files to activate history recording. The README news entries explain that history appends are performed through a long-running `sqlite3` process rather than launching a new SQLite process for every append. The stated reason is SQLite contention: starting a process for each append causes more contention because SQLite fsyncs when it exits.

The project also uses `add-zsh-hook`, and the README states that the `precmd` hook is installed when `sqlite-history.zsh` is sourced. You therefore do not need to add `add-zsh-hook precmd histdb-update-outcome` manually as older configurations did. The project records command outcomes after execution, then exposes the resulting database through the `histdb` command.

Queries are SQLite-backed searches rather than simple zsh history-file matches. A bare `histdb` invocation prints one screenful of history for the current host. Arguments are concatenated as query terms. The `%` character provides a wildcard between matching fragments, so `histdb this%that` matches a line containing `this` followed by `that` with zero or more characters between them. The README also documents `--host`, `-s`, and `--limit`, including examples such as `-s 522 --limit 10000` for viewing a larger slice of one session.

Installing zsh-histdb in a zsh startup file

The README requires `sqlite3` and the usual coreutils commands on `PATH`. It gives an installation directory under `$HOME/.oh-my-zsh/custom/plugins/zsh-histdb`, while explicitly noting that oh-my-zsh is not required. The clone command is:

mkdir -p $HOME/.oh-my-zsh/custom/plugins/
git clone https://github.com/larkery/zsh-histdb $HOME/.oh-my-zsh/custom/plugins/zsh-histdb

After cloning, source the integration file from `$HOME/.zshrc` and load the hook helper:

source $HOME/.oh-my-zsh/custom/plugins/zsh-histdb/sqlite-history.zsh
autoload -Uz add-zsh-hook

Start a new zsh session, run a command, and then query the database. The README's query examples use `histdb` with a search term, while `histdb --help` documents the available host, directory, session, and time filters. If you rely on zsh-autosuggestions, the README also documents configuring it to search the history database instead of the ordinary zsh history file.

The README does not document a package-manager installation, release artifact, or GitHub release workflow. It also does not specify a dedicated initialization command beyond sourcing `sqlite-history.zsh`, so a user should not expect `histdb-init` or a similar setup command based on the available documentation.

OS X setup, imported history, and incomplete metadata

OS X users have an extra configuration requirement. The README instructs them to set `HISTDB_TABULATE_CMD` before sourcing `sqlite-history.zsh`:

HISTDB_TABULATE_CMD=(sed -e $'s/\x1f/\t/g')

This setting changes the command used to tabulate data, replacing the unit separator character with a tab. Skipping it on the affected systems can leave the documented OS X integration incomplete.

Existing zsh history can be imported with the linked `go-histdbimport` and `ts-histdbimport` tools. The limitation is explicit: the normal history file does not contain metadata such as working directory or exit status. Imported commands can therefore appear in the database, but queries using `--in DIR` and similar metadata filters will not work as expected for those imported entries. Import is useful for preserving command text, not for reconstructing execution context that was never recorded.

The README also links an fzf integration, but it does not present it as the default installation path. A user who wants interactive selection would need to follow that separate section rather than assume that cloning `sqlite-history.zsh` automatically enables the full fzf experience.

Configuration and the limits of useful queries

Configuration is intentionally small. zsh-histdb treats `HISTORY_IGNORE` as a single glob pattern identifying commands that should not be saved. The README gives this example:

(ls|cd|top|htop)

Commands matched by that pattern are omitted from the database. This is useful for suppressing noisy commands, but it also means that query results are only as complete as the recording policy. The README does not document a separate option for retention, database size limits, or automatic pruning.

The `histdb-top` command summarizes frequent commands. `histdb-top dir` shows the most frequent directory for command execution. The README itself calls these commands "a bit useless," which is a useful indication that they are conveniences rather than the main reason to adopt the project.

There is another practical boundary. The README warns that `histdb` does not warn when the displayed results exceed one screenful. A user who wants the complete result set must raise the limit explicitly, for example with `--limit 1000` or a larger value. That behavior is easy to miss in scripts or during interactive review, so query limits should be checked before treating displayed history as complete.

Maintenance, upgrades, and a real alternative

The repository is not archived, and its last push was on 2026-09-18. It has no GitHub releases, so there is no release version or published upgrade cadence documented in the repository. The README's news section does document important maintenance events. In 2019, a schema change removed a database corruption bug involving `vacuum`, but the database required a non-backwards-compatible update. The README specifically says that installations sharing a history file need to be updated at the same time.

This makes zsh-histdb different from a simple shell alias collection. Database files and schema migrations are part of operating the tool. The repository includes `db_migrations/`, `histdb-migrate`, and `histdb-merge`, which reflects a more involved lifecycle than changing a zsh configuration line. The README also documents changes to the way remote database IDs are treated during synchronization and to process cleanup and WAL truncation.

A real alternative is ordinary zsh history when retaining command text is the main need. It has less metadata and fewer cross-host queries, but it avoids a separate SQLite database, `sqlite3` as a runtime dependency, migration steps, and synchronization behavior. For a single-machine user who mainly recalls recent command text, that simpler approach may be the better fit. zsh-histdb is more relevant when directory, host, session, timing, and exit status are part of the questions being asked.

Editorial conclusion

Adopt zsh-histdb if you regularly search zsh history by directory, host, session, time, or command outcome and can maintain sqlite3 on every participating machine. Do not adopt it if a plain history file is sufficient or if database migrations across shared installations are unacceptable. Verify the database migration path, OS X tabulation setting, hostnames, and the exact `sqlite-history.zsh` startup integration before replacing an established history workflow.

Frequently asked questions

Official sources

1. Issues
2. larkery/zsh-histdb on GitHub
3. License: MIT
4. README