Hammerspoon is a programmable automation engine for macOS that enables deep system-level control through a Lua scripting environment. By bridging high-level scripts with native Objective-C APIs, it allows users to interact with the operating system's accessibility tree, intercept hardware input streams, and manage the lifecycle of running applications.
The project distinguishes itself through an event-driven architecture that registers asynchronous hooks for system notifications and hardware events. This allows for real-time automation, such as remapping keyboard and mouse inputs, managing window layouts via grid-based positioning, and responding to changes in network status, battery levels, or display configurations. Its modular extension system supports the loading of self-contained units of functionality, enabling users to tailor the environment to specific workflows.
Beyond core automation, the platform provides a comprehensive suite of capabilities for network integration, media and hardware control, and data persistence. It includes tools for managing audio devices, interacting with professional control panels, rendering custom graphical overlays, and executing shell commands or system scripts. The environment also supports complex window management, including spatial navigation and tabbed grouping, alongside monitoring utilities for system hardware and diagnostic logging.
The project provides a command-line interface for managing configurations and includes built-in documentation servers to assist with script development.
