Hammerspoon is a macOS desktop automation tool that bridges the operating system with a Lua scripting engine.
The tool solves the problem of controlling and automating macOS system behavior by exposing operating system functionality through a set of extensions. Users write Lua scripts that interact with these extensions to control aspects of their OS X environment. The approach is minimal at its core—Hammerspoon itself is just the bridge—but gains power through extensions that provide access to specific system capabilities.
Hammerspoon suits developers and power users who want to automate their macOS workflow through scripting rather than through graphical interfaces. It is appropriate for projects ranging from simple keyboard shortcuts and window management to complex system monitoring and application control. The tool requires users to write configuration code in a Lua file; it does nothing out of the box. The README positions Hammerspoon as an alternative to Mjolnir, its predecessor, noting that while Mjolnir aims for minimalism with externally managed extensions, Hammerspoon provides a more integrated experience with extensions bundled into the application.
The project maintains active continuous integration testing and code coverage tracking. Community support is organized across multiple channels including a Discord server, an IRC channel, a Google Group, and a wiki with user-contributed sample configurations. The project accepts contributions through a documented contribution guide and maintains comprehensive API documentation and a getting started guide for new users.
