Shell Setup

Shell completions

The zsh/ package adds ${XDG_DATA_HOME:-~/.local/share}/zsh/site-functions to fpath before zsh-autocomplete runs compinit.

Generated completions are stowed for the two local CLIs:

• dot completions bash|fish|zsh writes the stowed dot completions in this repo.
• context completions bash|fish|zsh writes the stowed context completions in this repo.
• _omarchy is a stowed zsh completion wrapper for dynamic Omarchy subcommands.

Installed package completions are also wired into common aliases where needed. handoffs completes through _notes and runs notes handoffs.

Zsh also has a live generated completion:

• mise completion zsh is generated at shell startup into the live, non-stowed _mise path and refreshed when the mise binary is newer than the cached completion.

The live _mise file is intentionally not version-controlled; it tracks the installed mise binary on each machine.

watchexec is managed through mise, so mise watch <task> can rerun short feedback tasks such as tests and type checks when files change. Keep persistent development servers under the project’s documented server workflow or Pitchfork instead.

Editing keys

fzf’s native zsh integration provides fuzzy history search with Ctrl+R, file and directory insertion with Ctrl+T, directory changes with Alt+C, and fuzzy tab completion.

The zsh config restores the standard editing bindings used by this setup after plugins load, including Delete as forward-delete. dot doctor checks the Delete binding and reports drift when a plugin or local override changes it.

Small helpers

The shell initialises zoxide as zd, which also backs Omarchy’s cd alias. Directory changes teach zoxide which paths are used most often, while zd <query> jumps directly to a ranked match.

Omarchy’s ff alias opens an fzf file picker with previews. fast runs Fastfetch without replacing that picker. cat and b use bat’s normal highlighted output, while bp uses plain output.

The shell keeps a few typo and navigation helpers close to the aliases. For example, cwd prints a short reminder that the real command is pwd, then runs pwd so the mistake still returns useful output.

Run update to select maintenance steps with Gum. Dotfiles and Omarchy remain separate choices, while each enabled Topgrade step can be selected independently. Selected work runs in the displayed order: Dotfiles, Omarchy, then Topgrade. GitHub CLI extensions and Yazi start selected; Mise and the remaining steps are opt-in because Omarchy already updates mise-managed tools. Selected Topgrade steps run together through topgrade --only; selecting every Topgrade step uses the normal full topgrade command instead.

The Omarchy step re-stows the public dotfiles before updating, ensuring the native post-update.d patch hook and current command wrappers are installed. It redirects Quattro’s global mise writes to ~/.local/state/mise/omarchy-config.toml, keeping mise/.config/mise/config.toml under dotfiles control during the complete update, not just normal shell commands.

Use update -y or update --yes, or run it in a non-interactive shell, to select every step without prompting. Agent-driven runs without a controlling terminal route internal sudo calls through a temporary pkexec helper so authentication can use the desktop PolicyKit prompt. Interactive terminals keep normal sudo credential caching. The sequence stops if a selected step fails.