# Hammerspoon: macOS Automation Through a Lua Bridge

> Hammerspoon is an MIT-licensed macOS app that exposes system APIs to a Lua scripting engine, so window management, hotkeys and app control live in one init.lua file. It is not a click-to-configure utility, and that is the point.

**Hammerspoon/hammerspoon** — Staggeringly powerful macOS desktop automation with Lua

- Repository: https://github.com/Hammerspoon/hammerspoon
- Website: http://www.hammerspoon.org
- Stars: 16,200 · Forks: 721
- Language: Objective-C
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/hammerspoon-hammerspoon

## What Hammerspoon actually solves on macOS

The README describes Hammerspoon as "a bridge between the operating system and a Lua scripting engine." That sentence is the whole product. macOS ships with window snapping, hotkeys and app switching spread across System Settings, third-party menu bar apps and accessibility panes. Hammerspoon replaces that spread with one scripting surface: extensions expose pieces of system functionality, and you write Lua to drive them.

The intended user is someone who already thinks in scripts. If your mental model is a preferences window with checkboxes, Hammerspoon will feel like being handed a compiler instead of a recipe. The README is explicit that "out of the box, Hammerspoon does nothing" and that you must create ~/.hammerspoon/init.lua yourself. There is no default behaviour to react to, no bundled preset to disable. That is a deliberate design position, not an unfinished one, and it filters the audience sharply.

## The Lua bridge and the extension model

Architecturally the repository is an Objective-C application with a Lua runtime embedded through LuaSkin, a directory that sits at the top level of the repo. The extensions/ directory holds the modules that expose system APIs to Lua. This is why the primary language is Objective-C while every example a user writes is Lua: the Objective-C side does the talking to macOS, and Lua is the control surface.

Hammerspoon is a fork of Mjolnir, and the README explains the split directly. Mjolnir "aims to be a very minimal application, with its extensions hosted externally and managed using a Lua package manager." Hammerspoon chose the opposite trade: extensions ship with the app for "a more integrated experience." The cost is that extension coverage is tied to the release cycle rather than to whatever a package manager happens to publish. The benefit is that the API surface is consistent and documented in one place.

Spoons are the distribution unit for user-written modules, and the repository carries a SPOONS.md file at the top level describing them. The README points to a wiki page of Sample Configurations rather than bundling examples, which tells you where the project expects configuration knowledge to live: outside the repository, in the community.

## Installing Hammerspoon and writing a first init.lua

The README gives two install paths. The manual one is to download the latest release and drag Hammerspoon.app from Downloads to Applications. The Homebrew path is a single cask command:

```bash
brew install hammerspoon --cask
```

After either path, launch the app. The README states that it does nothing until ~/.hammerspoon/init.lua exists, so create that directory and file. The README itself does not print a sample binding; the Getting Started Guide and the API docs linked from it are where the project says to look for one. What you should see after saving a configuration is the app picking it up without a reinstall. The README lists the Getting Started Guide at hammerspoon.org/go, the API docs at hammerspoon.org/docs, and the FAQ at hammerspoon.org/faq as the documented path from an empty file to a real configuration.

## Where Hammerspoon is the wrong tool

The empty default is the first failure mode. A user who installs Hammerspoon expecting window snapping to appear gets nothing at all, and the README does not pretend otherwise. If you want behaviour without writing code, Hammerspoon is the wrong choice.

Platform is the second boundary. The README describes the project as automation "of OS X" and the repository topics list macos and osx. Nothing in the repository documents a Windows or Linux build, so treating Hammerspoon as cross-platform is a mistake.

Third, the documentation set is split across the README, the website, the wiki and an IRC channel. The README does not document rollback, configuration validation, or what happens when an extension call fails. Debugging a broken init.lua means reading the console output the app produces and consulting the API docs, not following a troubleshooting chapter in the repository. That is a real cost for anyone who wants a support contract rather than a community.

## Hammerspoon compared with Karabiner-Elements

Karabiner-Elements and Hammerspoon overlap on keyboard remapping, which is why the comparison comes up, but the approaches differ in kind. Karabiner works at the driver and input-event layer: it intercepts and rewrites keyboard events before applications see them, and it is configured through JSON rule files rather than a scripting language.

Hammerspoon sits above that layer, in a Lua engine that calls macOS APIs. Its reach extends past the keyboard to window control, application launching and whatever else the bundled extensions expose. The trade is depth versus breadth. If your problem is purely that Caps Lock should behave like Escape, a dedicated remapper is the narrower and more predictable instrument. If your problem is that a keypress should move a window, switch an app and run a shell command in sequence, that is scripting, and Hammerspoon is built for it. The two are not mutually exclusive, and the README does not claim they are.

## Maintenance, releases and the MIT licence

The last push to the repository was on 2026-07-08, and the most recent release listed is 1.1.1 from 2026-02-26, following 1.1.0 in December 2025 and 1.0.0 in August 2024. The project is not archived. Release cadence is not fast, which matters for a tool whose value depends on keeping pace with macOS API changes: when Apple alters an accessibility or window API, the extension wrapping it needs updating before your init.lua keeps working.

Upgrade cost is mostly yours, not the project's. Because configuration lives in ~/.hammerspoon/init.lua, an app update does not overwrite your setup. The risk sits in extension behaviour changing between releases, which the README does not address with a changelog or migration guide.

The licence is MIT. That permits commercial and private use, modification and redistribution with the licence and copyright notice retained. It is a permissive licence with no copyleft obligation, but this is a summary of the identifier, not legal advice; read the LICENSE file in the repository if the terms matter to your organisation.

## Conclusion

Adopt Hammerspoon if you are comfortable writing Lua and want window management, hotkeys and app control in one versionable file; skip it if you want a GUI preferences window or need Windows support, since the README describes automation of OS X and names no Windows path. Before committing, verify that your init.lua loads cleanly and that the extensions you plan to use appear in the API docs at hammerspoon.org/docs, because the README documents no rollback or config validation beyond that.

## FAQ

### What is Hammerspoon used for?

It is used to automate macOS by writing Lua scripts against system APIs exposed as extensions. The README describes it as a bridge between the operating system and a Lua scripting engine.

### What language does Hammerspoon use?

You write Lua. The application itself is written primarily in Objective-C, with the Lua runtime embedded through LuaSkin, but user configuration goes in ~/.hammerspoon/init.lua.

### How to install Hammerspoon on a Mac?

Download the latest release and drag Hammerspoon.app into Applications, or run brew install hammerspoon --cask. The app does nothing until you create ~/.hammerspoon/init.lua.

### Is Hammerspoon free and open source?

Yes. The repository is licensed under MIT, which permits use, modification and redistribution provided the licence and copyright notice are retained.

### How does Hammerspoon differ from Karabiner?

Karabiner works at the keyboard event layer and is configured with JSON rules, while Hammerspoon runs a Lua engine that calls macOS APIs and reaches beyond the keyboard to windows and applications. The two can be used together.

## Sources

- [Hammerspoon/hammerspoon on GitHub](https://github.com/Hammerspoon/hammerspoon)
- [License: MIT](https://github.com/Hammerspoon/hammerspoon/blob/master/LICENSE)
- [Project website](http://www.hammerspoon.org)
- [README](https://github.com/Hammerspoon/hammerspoon/blob/master/README.md)
- [Releases](https://github.com/Hammerspoon/hammerspoon/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hammerspoon-hammerspoon