Hammerspoon

Hammerspoon is a tool that turns macOS into an environment configured for a specific workflow. In essence it’s a light add-on that listens to keyboard and system events and performs actions described in Lua code. No extra UI or “setup wizards”: behaviour is set directly, as rules and scenarios.

The main value of Hammerspoon is that it works not as “yet another remapper” but as a logic engine:

Launching and focusing apps, windows (positions, layouts, monitors), window navigation, media control, system actions, logic (checks, delays, fallbacks).

In my practice it looks like this:

• Caps Lock (my “super key” layer): Caps Lock + any digit or key is tied to launching or focusing specific apps. This is my main way of moving around the system without the Dock or search.

• Space layer: holding Space turns on a separate mode that gathers quick actions, including media control and launching additional apps.

• Backtick layer: holding backtick is tied to Leader Key: it’s the entry to sublayers where, for example, individual keys open the right folders in Finder or specific projects in ChatGPT. I described this earlier.

Technically all of this is described in the init.lua configuration. The standard path:

~/.hammerspoon/init.lua

It’s convenient to keep the config as code: version it, move it to other devices, develop it step by step. In my setup the configuration syncs through iCloud (via a symlink): the system sees the standard ~/.hammerspoon/ path, but the config actually sits in an iCloud Drive folder, so the same behaviour is available on all devices.

A basic example of what an action looks like in Hammerspoon: a hotkey is created and tied to a function that does the required action, for example opens an app. In the real config this is complemented by layers, modal modes and scenarios that make controlling the system fast and predictable.

What launching an app looks like in Hammerspoon

The basic construct in the config looks like this:

hs.hotkey.bind(hyper, "i", function()
hs.application.open("path to the app")
end)

• hs.hotkey.bind(...) registers a key combination

• hyper is a set of modifiers (the Hyper layer)

• “i” is the trigger key inside the layer

• function() ... end is the action performed on press

• hs.application.open(...) opens an app by its exact path

An alternative for many tasks: hs.application.launchOrFocus("AppName").

In the next post I’ll talk about the Window Manager in Hammerspoon.