Shell History

Shell History, FZF, and Atuin Integration Guide

This guide describes how shell history is managed on this system. We use a three-tiered history search system that combines Atuin (local SQLite database + encrypted cloud sync), FZF (fuzzy finder widget), and Zsh Substring Search (instant line-filtering).

All three systems are configured to work simultaneously without conflict.

⌨️ Keybindings Cheatsheet

Action	Keybinding	Search Engine	Description
Atuin Full Search	`Ctrl + R`	Atuin	Opens the full-screen Atuin interactive search TUI.
Atuin Up-Search	`Up Arrow`	Atuin	Opens the Atuin quick-search interface pre-filled with the current command.
FZF History Search	`Alt + r` or `Alt + h`	FZF	Launches FZF fuzzy finder over your shell history.
Zsh Substring Search Up	`Alt + p`	Zsh Substring	Filters history backward matching whatever you typed.
Zsh Substring Search Down	`Alt + n`	Zsh Substring	Filters history forward matching whatever you typed.

🧠 Explanation of Key Codes & How to Type Them

You may see these key codes in config/zsh/keybinds.zsh or config/zsh/fzf.zsh. Here is how they map to your keyboard:

1. Arrow Keys (`\e[A`, `\eOA`, `\e[B`, `\eOB`)

\e represents the Escape character.
\e[A and \eOA are the terminal escape sequences generated when you press the Up Arrow key.
\e[B and \eOB are the escape sequences generated when you press the Down Arrow key.
How to type them: Simply press the Up or Down arrow keys on your keyboard. Zsh binds both sequence styles to ensure arrow keys work in normal terminals as well as multiplexed/application environments like Tmux or Vim.

2. Alt Bindings (`\er`, `\eh`, `\ep`, `\en`)

Zsh represents the Alt (or Meta/Option) modifier using the \e (escape) prefix.
\er translates to Alt + r
\eh translates to Alt + h
\ep translates to Alt + p (where p stands for Previous)
\en translates to Alt + n (where n stands for Next)
How to type them: Hold down the Alt key (or the Option key on a Mac) and press the corresponding letter key (r, h, p, or n).

🚧 Conflict Resolution Analysis (Niri, Foot, Tmux)

We have engineered these keybindings to prevent conflicts across the layout layers:

1. Niri (Wayland Compositor)

Status: No Conflicts.
Niri binds system-wide commands using the Super (Windows/Cmd) key as a modifier. It does not intercept Alt or Ctrl bindings, so they pass directly to your terminal.

2. Foot (Terminal Emulator)

Status: No Conflicts.
Foot does not capture Alt-r, Alt-h, Alt-p, or Alt-n by default, passing the escape codes cleanly to Zsh.

3. Tmux (Terminal Multiplexer)

Status: Conflict Resolved.
Your Tmux configuration binds Alt + h/j/k/l globally to switch terminal panes without needing the prefix key.
Because Tmux intercepts Alt + h (M-h), pressing Alt + h inside a Tmux session would switch panes instead of opening FZF history.
Resolution: We added Alt + r (\er) as a dedicated history shortcut for FZF. Tmux does not intercept Alt + r, so it will always work perfectly to launch FZF history search inside and outside of Tmux.

⚙️ Configuration (Nix Module Options)

If you wish to change whether Atuin binds the Up arrow key, you can configure the bindUpArrow option in your host configuration:

# hosts/<host>/modules/modules.nix
modules.shell.atuin = {
  enable = true;
  bindUpArrow = true; # Set to false if you want the Up/Down arrow keys to do Zsh Substring Search instead of Atuin search.
};