Hammerspoon — Staggeringly Powerful macOS Automation with Lua

Introduction

Hammerspoon is a macOS automation tool that exposes system-level APIs to a Lua scripting environment. It replaces multiple single-purpose utilities by letting you write short scripts for window management, application control, file watching, network events, and virtually any other macOS interaction.

What Hammerspoon Does

• Manages window positions and sizes with Lua functions
• Binds global hotkeys to arbitrary actions
• Watches for Wi-Fi, USB, screen, and battery events
• Controls audio devices, volume, and playback
• Provides a built-in IPC mechanism and HTTP server for external integration

Architecture Overview

Hammerspoon embeds a LuaJIT interpreter inside a native Objective-C application. System functionality is exposed through extension modules (hs.window, hs.screen, hs.application, etc.) that wrap Cocoa and Carbon APIs. When the user edits init.lua and reloads, Hammerspoon re-evaluates the script, registers hotkeys and event watchers, and keeps the Lua VM running in the background.

Self-Hosting & Configuration

• Install via Homebrew: brew install --cask hammerspoon or download from the website
• Grant Accessibility permissions when prompted on first launch
• All configuration lives in ~/.hammerspoon/init.lua
• Install community Spoons (plugin bundles) via SpoonInstall or manually
• Reload configuration instantly from the menu bar icon or a bound hotkey

Key Features

• Scriptable access to nearly every macOS system API
• Spoons plugin system for reusable, shareable configuration modules
• Built-in console for interactive Lua experimentation
• Event watchers for Wi-Fi SSID changes, USB connect/disconnect, and screen layout changes
• URL scheme handler for triggering actions from external tools or scripts

Comparison with Similar Tools

• Karabiner-Elements — Focused on keyboard remapping only; Hammerspoon covers broader automation
• BetterTouchTool — GUI-driven input customization with paid license; less scriptable
• Raycast — App launcher with extensions; Hammerspoon is lower-level and fully code-driven
• Shortcuts (macOS) — Apple's visual automation; limited system-level access compared to Hammerspoon
• AppleScript/JXA — Built-in macOS scripting; slower and less ergonomic for system-level tasks

FAQ

Q: Do I need to know Lua? A: Basic Lua is easy to pick up, and the Hammerspoon API documentation includes copy-paste examples. Most configurations are under 50 lines.

Q: What are Spoons? A: Spoons are self-contained plugin modules that package reusable Hammerspoon functionality. Examples include window layout managers, app watchers, and clipboard tools.

Q: Does Hammerspoon affect system performance? A: Hammerspoon uses minimal resources when idle. Event watchers and hotkey listeners are passive; CPU usage only spikes briefly when a script action executes.

Q: Can Hammerspoon control apps that don't support AppleScript? A: Yes. Hammerspoon uses the Accessibility API, which works with any app that exposes standard UI elements, regardless of AppleScript support.

Sources

• https://github.com/Hammerspoon/hammerspoon
• https://www.hammerspoon.org/