Hammerspoon
A macOS automation tool that runs Lua scripts to control your Mac's windows, keys, and system.
- Stars
- 16.4k
- Forks
- 739
- Licence
- MIT
- Language
- Objective-C
- Last update
- 4 months ago
- Type
- App
What it is
Hammerspoon is a macOS tool that acts as a bridge between the operating system and a Lua scripting engine. It ships with extensions that expose many system features, so you can write Lua scripts to automate parts of your Mac. Out of the box it does nothing; you write your own configuration file to decide what it does.
- Write a ~/.hammerspoon/init.lua file that binds keyboard shortcuts to actions
- Script system behavior through its extensions, such as window and system features
- Follow the sample configurations shared on the project wiki as a starting point
- Ask questions and get help through the project's IRC channel, Google Group, or Discord
Great for
- Mac users comfortable writing small scripts who want custom keyboard shortcuts or window behavior
- Power users who want to automate repetitive desktop tasks on macOS
- People who used Mjolnir and want a more integrated version with built-in extensions
- Developers who want to script their own macOS environment
Not ideal for
- People who want a ready-made app with no configuration, since it does nothing until you write Lua code
- Users on other operating systems, because it is macOS only
- Anyone unwilling to learn basic Lua, since scripting is the main way to use it
How to get it
- 1
Install with a package manager
You'll need: macOS
Install with Homebrew
brew install hammerspoon --cask - 2
Run it
- Install Hammerspoon.app, either by downloading the latest release or with Homebrew
- Move Hammerspoon.app to your Applications folder and open it
- Create the file ~/.hammerspoon/init.lua
- Add Lua code to init.lua to define your first automation, then reload it
- 3
Get the most out of it
- Read the Getting Started Guide and API docs on hammerspoon.org
- Browse the Sample Configurations wiki page for working examples
- Check the FAQ when setup questions come up
- Join the #hammerspoon IRC channel on Libera or the Discord for help
Downloads
Strengths
- Built on Lua, a simple and widely used scripting language
- Extensions expose many system features, and API docs are available online
- Open source under the MIT license with an active community and CI testing
Trade-offs
- Requires writing code, so it is not a point-and-click tool
- MacOS only, and the README does not list supported macOS versions
- Its extension coverage is still growing according to the project's own future plans
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| hammerspoon (this) | 16.4k | App | intermediate | 4 months ago | Mac users comfortable writing small scripts who want custom keyboard shortcuts or window behavior |
| mas | 12.4k | CLI | beginner | 7 days ago | Developers who script new Mac setups |
| SDWebImage | 25.6k | Library | intermediate | 7 months ago | iOS or macOS app developers who need to show remote images in lists or grids |
| macOS-Security-and-Privacy-Guide | 22.6k | Learning resource | intermediate | 4 days ago | Mac owners who want a checklist of security and privacy settings to work through |
| macos | 21.7k | Dev tool | intermediate | 29 days ago | Developers who need to test software on macOS from a Linux machine |
| atom | 60.7k | App | beginner | 3.8 years ago | Developers who want a desktop code editor they can customize with packages |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.