zgod

Interactive shell history search with fuzzy, regex, and glob matching.

Features

• Match modes: fuzzy / regex / glob
• Filters: current directory, deduplication, fail filter (include/exclude/only)
• History exclusion filters: exclude commands from history recording
• Persistent storage: history is stored locally in SQLite
• Configurable UI: prompt, colors, layout, multiline behavior
• Custom keybindings
• Supported shells: bash, zsh, fish, and powershell

Usage

Press Ctrl+R to open the search UI. Start typing to filter results. If the UI is already open, press Ctrl+R again to move to the next result.

Installation

Quick install

Unix (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/zigai/zgod/master/install.sh | sh

Windows:

irm https://raw.githubusercontent.com/zigai/zgod/master/install.ps1 | iex

Go install

go install github.com/zigai/zgod@latest

Prebuilt binaries

Download the latest binaries from the GitHub Releases page.

Build from source

git clone https://github.com/zigai/zgod.git
cd zgod
go build -o zgod .

Setup

Automatic

zgod install bash   # or zsh, fish, powershell

Manual

If you prefer manual setup, add the snippet for your shell to your shell config file.

Bash (~/.bashrc)

if command -v zgod >/dev/null 2>&1; then eval "$(zgod init bash)"; fi

Zsh (~/.zshrc)

if command -v zgod >/dev/null 2>&1; then eval "$(zgod init zsh)"; fi

Fish (~/.config/fish/conf.d/zgod.fish)

type -q zgod; and zgod init fish | source

PowerShell ($PROFILE)

if (Get-Command zgod -ErrorAction SilentlyContinue) { Invoke-Expression (& zgod init powershell) }

Keybindings

Key	Action
enter	Accept selection
esc / ctrl+c	Cancel
up / ctrl+p	Move up
down / ctrl+n / ctrl+r	Move down
ctrl+s	Cycle match mode (fuzzy / glob / regex)
ctrl+d	Toggle CWD filter
ctrl+g	Toggle deduplication
ctrl+f	Cycle fail filter (include/exclude/only)
alt+t	Cycle date sort (newest/oldest/off)
alt+f	Fuzzy mode
alt+r	Regex mode
alt+g	Glob mode
alt+p	Preview multiline command (popup mode only)
ctrl+1 … ctrl+9, ctrl+0	Accept visible result 1-10
?	Help overlay

Mouse is also supported in compatible terminals: wheel scrolls the result list, hovering a result highlights it, left-clicking a result accepts it, footer shortcuts and top-right pills can be clicked, and clicking in the input moves the cursor.

Configuration

Default paths:

• Unix (Linux/macOS):
  • config file: ~/.config/zgod/config.toml
  • history database: ~/.local/share/zgod/history.db
• Windows:
  • config file: %APPDATA%\zgod\config.toml
  • history database: %LOCALAPPDATA%\zgod\history.db

All fields are optional.

[db]
path = ""  # default: platform-specific history path; custom paths must be absolute or use ~/

[filters]
ignore_space = true       # skip commands starting with a space
exit_code = [130]         # exit codes to skip, e.g. 130 = Ctrl+C
command_glob = []         # command glob patterns to skip, e.g. ["cd *", "ls", "exit"]
command_regex = []        # command regex patterns to skip, e.g. ["^sudo "]
directory_glob = []       # directory glob patterns to skip, e.g. ["/tmp/**"]
directory_regex = []      # directory regex patterns to skip, e.g. ["^/tmp"]
max_command_length = 0    # skip commands longer than this (0 = disabled)

[theme]
prompt = "> "
prompt_color = "cyan"
match_color = "yellow"
match_bold = true
match_underline = true
match_bg = ""
selected_bg = "24"
selected_fg = ""
selection_bar_show = true
selection_bar_char = "▌ "
selection_bar_color = "14"
selection_full_line = true
mode_color = "240"
border_color = ""

[display]
time_format = "relative"        # relative | absolute
duration_format = "auto"        # auto | ms | s
show_hints = true               # show footer hints
show_directory = false          # show directory column in search results
instant_execute = false         # execute accepted command immediately
enable_fuzzy = true             # enable fuzzy match mode
enable_regex = true             # enable regex match mode
enable_glob = true              # enable glob match mode
cwd_boost = 50                  # ranking boost for commands from current directory
default_scope = "normal"        # normal | cwd
default_mode = "fuzzy"          # fuzzy | regex | glob
default_fail_filter = "include" # include | exclude | only
startup_limit = 10000           # max history entries loaded at startup
hide_multiline = false          # hide multiline commands from results
multiline_preview = "popup"     # popup | preview_pane | expand | collapsed
multiline_collapse = " "        # symbol to replace newlines in collapsed view

[keys]
mode_next = "ctrl+s"
mode_fuzzy = "alt+f"
mode_regex = "alt+r"
mode_glob = "alt+g"
toggle_cwd = "ctrl+d"
toggle_dedupe = "ctrl+g"
toggle_fails = "ctrl+f"
sort_history = "alt+t"
accept = "enter"
cancel = "esc"
up = "up"
down = "down"
page_up = "pgup"
page_down = "pgdown"
top = "home"
bottom = "end"
select_1 = "ctrl+1" # accept 1st visible result
select_2 = "ctrl+2"
select_3 = "ctrl+3"
select_4 = "ctrl+4"
select_5 = "ctrl+5"
select_6 = "ctrl+6"
select_7 = "ctrl+7"
select_8 = "ctrl+8"
select_9 = "ctrl+9"
select_0 = "ctrl+0" # accept 10th visible result
help = "?"
preview_command = "alt+p"

License

MIT