Hammerspoon

About

Hammerspoon is a tool for automating macOS. At its core, it connects the operating system to a Lua scripting engine, and a set of extensions exposes specific system functionality to the user. You can write Lua code that interacts with macOS APIs for applications, windows, mouse pointers, filesystem objects, audio devices, batteries, screens, low-level keyboard and mouse events, clipboards, location services, wifi, and more. Typically, you write a Lua configuration file that connects events to actions, such as binding a keyboard shortcut to a series of window operations, running commands when your wifi connects to your home network, or showing an alert when your battery drops below a set percentage.

To install Hammerspoon, download the latest release and drag the application to /Applications/. Out of the box, Hammerspoon does nothing. You need to create a Lua script at ~/.hammerspoon/init.lua using its APIs and standard Lua APIs. The Getting Started Guide and full API documentation are available to help new users, and pre-made plugins called Spoons can be explored as well.

Hammerspoon can be extended in two ways: with pure Lua scripts that offer helper functions, or with Objective-C extensions that expose new areas of system functionality. Contribution guidelines are available on GitHub. Help is available through a Discord server, and bugs or suggestions can be reported through the issue tracker.