Hammerspoon: A Lua‑Powered macOS Automation Tool

macOS users often find themselves repeating the same drag‑and‑drop or menu clicks every day. Whether you’re a developer, designer, or just a power user, automating those habits can save hours of grind. That’s where Hammerspoon steps in: a lightweight, open‑source application that exposes the macOS API to the Lua scripting language. With Hammerspoon you can:

• Create hotkeys for app launch, window tiling, or media control.
• Automate clipboard history, notifications, or file management.
• Extend the OS with custom modules written in Objective‑C or Swift.
• Hook into hardware events (e.g., Bluetooth, keyboard LEDs, Stream Deck buttons).
• Integrate with external services (Dropbox, GitHub, etc.) via Lua HTTP libraries.

Getting Started

1. Install Hammerspoon

# Using Homebrew Cask
brew install --cask hammerspoon

Alternatively, download the latest release from the GitHub releases page and drag the Hammerspoon.app into Applications.

2. Set Up Your First Script

On first launch, Hammerspoon creates a ~/.hammerspoon/ directory. Inside it place a file named init.lua – this is the main configuration file.

-- ~/.hammerspoon/init.lua
hs.loadSpoon("Window")

-- Example: Toggle the Finder window on Cmd‑Shift‑F
hs.hotkey.bind({"cmd", "shift"}, "F", function()
  local f = hs.application.get("Finder")
  if f then
    f:activate()
    f:hide()
  else
    hs.osascript.applescript('tell application "Finder" to activate')
  end
end)

Save the file and press Cmd‑Alt‑F (the default hotkey for reloading). Your custom keybinding should now work.

Extending with Hooks & Modules

Hammerspoon ships with a library of "extensions" that expose various macOS services: hs.window, hs.pathmonitor, hs.audiodevice, etc. Additional extensions can be found on its dedicated extensions repository or written directly in C/Objective‑C and compiled into your Hammerspoon build.

-- Example: Set a dynamic window layout
hs.hotkey.bind({"cmd", "shift"}, "W", function()
  local win = hs.window.focusedWindow()
  if win then win:move({x=0, y=0, w=0.5, h=1}) end
end)

You can also use third‑party Lua libraries via standard package managers (luarocks). Hammerspoon’s hs.http module is handy for creating simple web hooks.

Community & Resources

• Documentation – The official Getting Started Guide and API Docs are indispensable.
• Examples – Browse and copy sample init.lua configurations from the repo’s samples/ directory.
• Support – Join the #hammerspoon IRC channel on Libera or the Google Group.
• Contributing – Fork the repo, run make test in the root, and submit pull requests. The project uses a strict linting/CI pipeline.

Tips for Power Users

1. Reload Efficiently – Press Cmd‑Option‑F to reload your config without restarting the app.
2. Use Spoon Support – hs.loadSpoon("<name>") loads third‑party libraries like Window or Desktop.
3. Debug with Console – hs.debug.disable() can hide debug output, or use print statements to trace logic.
4. Automate On Login – Add the ~/.hammerspoon/init.lua to your login items so scripts start on boot.
5. Create Reusable Modules – Place Lua modules in ~/.hammerspoon/modules/ and require("module") from init.lua.

Next Steps

• Build your own automation toolkit: add a custom media controller, create a window tiling manager, or automate your coding workflow.
• Experiment with Stream Deck or touch bar integration using Hammerspoon extensions.
• Explore the Hammerspoon Extension Wiki for advanced features.

By marrying the simplicity of Lua with the depth of macOS APIs, Hammerspoon lets you program your desktop into a tailored, responsive environment. Dive in, start scripting, and watch your productivity soar.