See every keyboard shortcut on this machine at once — Karabiner, skhd, Ghostty, tmux, Herdr, and Neovim. Find what shadows what, and find a chord that is still free.
Requires Bun ≥ 1.3.14.
./scripts/install.shLinks $HOME/.local/bin/agentkeys to this checkout. Set AGENTKEYS_INSTALL_BIN_DIR and AGENTKEYS_INSTALL_STATE_DIR to override the install locations.
agentkeys doctor
agentkeys explain --key cmd+shift+v
agentkeys find-available --modifier cmd+shift --layer skhd
agentkeys list-bindings --format tableagentkeys --agent-teaser # one line
agentkeys --agent-help # the runbook
agentkeys list-bindings --help-json # machine-readable flags, per commandMachine formats emit the stable {schema_version, ok, error, data} envelope
on stdout: list-bindings in json (the default) or yaml, and explain --format json. Exit 0 on success, exit 1 with ok:false and a snake_case
error.code on a domain failure, exit 2 for a usage fault — which is never an
envelope, so stdout is parseable whenever a command actually ran. The keys
skill in skills/ teaches an agent to drive all of it.
Each layer is read from the location its own tool documents, so a plain machine and a dotfiles checkout stowed into place are the same paths.
| Layer | Source |
|---|---|
| karabiner | ~/.config/karabiner/karabiner.json |
| skhd | ~/.config/skhd/skhdrc |
| ghostty | ghostty +list-keybinds, falling back to ~/.config/ghostty/config |
| tmux | ~/.config/tmux/tmux.conf, its literal source-file targets, and ~/.config/tmux/conf.d/*.conf |
| herdr | vendored defaults overlaid by ~/.config/herdr/config.toml (XDG_CONFIG_HOME honored), when the app is installed |
| nvim | ~/.config/nvim/init.lua and ~/.config/nvim/lua/plugins/*.lua |
Ghostty prefers the binary, because its config file holds only what you overrode — the app ships around ninety-five more bindings. Herdr has no dump command, so its defaults are vendored from the upstream source, version-stamped, and joined only when the app is present.
Every path is overridable: AGENTKEYS_KARABINER_CONFIG, AGENTKEYS_SKHD_CONFIG, AGENTKEYS_GHOSTTY_CONFIG, AGENTKEYS_GHOSTTY_BIN (empty disables the probe), AGENTKEYS_HERDR_CONFIG, AGENTKEYS_HERDR_BIN (empty treats the app as absent), AGENTKEYS_TMUX_CONFIG, and AGENTKEYS_NVIM_CONFIG.
Priority follows the hosting paths: tmux and Herdr run inside Ghostty, and Neovim runs directly in Ghostty or inside either multiplexer. Tmux and Herdr never see the same keystroke, so the same key in those sibling layers is never a conflict.
agentkeys doctor names every file it read, so a layer whose config is missing never reads as a layer with nothing to report.
bun install
bun run check # lint + typecheck + test
bash scripts/smoke.sh # every command end to end, throwaway HOMECONTEXT.md holds the domain glossary; docs/adr/ the decisions that shaped
the design.