Hammerspoon is the programmable layer — anything that requires Lua logic, low-level window manipulation, or system events that BTT and KM can’t reach.
Config: ~/.hammerspoon/init.lua — the main entry point. Modular configs split into separate files and required from init.lua.
HammerFlow manages Hammerspoon hotkey bindings in TOML configuration files, making them readable and maintainable without editing raw Lua.
Config location: ~/.hammerspoon/hammerflow.toml (or similar — check init.lua for exact path)
Format:
[[bindings]]
key = "h"
mods = ["ctrl", "alt"]
action = "some_action"
description = "Do something"
Spoons are Hammerspoon plugins stored in ~/.hammerspoon/Spoons/. List installed:
ls ~/.hammerspoon/Spoons/
Common useful Spoons: MiroWindowsManager (window grid), ReloadConfiguration (auto-reload on save), SpoonInstall (install other Spoons).
Hammerspoon can call BTT named triggers and vice versa:
Hammerspoon → BTT:
hs.urlevent.openURL("btt://trigger_named/?trigger_name=TRIGGER_NAME")
Reload config:
hs.reload()
Or use the menu bar Hammerspoon icon → Reload Config.
Open the Hammerspoon console from the menu bar icon to see print output and errors. Add print("debug message") anywhere in Lua for tracing.
Watch the console when reloading config — syntax errors appear immediately.