Installation
Right then. Let's get the thing installed.
Step 1: Download Hammerspoon
Go to hammerspoon.org and download the latest release. It's a standard Mac .zip — unzip it, drag Hammerspoon.app to your Applications folder, open it.
When you first launch it, macOS will ask if you want to allow it. You do. It'll also ask for Accessibility permissions — this is required because Hammerspoon needs to be able to move the mouse and respond to keyboard events. Go to System Settings → Privacy & Security → Accessibility and enable it.
If Hammerspoon doesn't appear to be doing anything after you enable Accessibility, quit it and reopen it. macOS sometimes needs a restart of the app after granting permissions.
Step 2: Find Your Config File
Hammerspoon runs from a single config file:
~/.hammerspoon/init.lua
That's in your home directory, in a hidden folder called .hammerspoon. If it doesn't exist yet, Hammerspoon will create it when you first open it.
The easiest way to open it is from the Hammerspoon menubar icon — click it and choose Open Config.
Step 3: Verify It's Working
Before writing anything, let's confirm Hammerspoon is alive. Open your config file and add this one line:
hs.alert.show("Hammerspoon is working")
Save the file. Click the Hammerspoon menubar icon and choose Reload Config. You should see a small alert pop up on screen. If you do — great, everything's wired up. Delete that line before moving on.
Step 4: Understand the Structure
Your init.lua is the entry point. You can write everything directly in it, or you can split things into separate files and require them from init.lua. For a jiggler this small, putting it all in init.lua is fine.
On to the actual code.