Hammerspoon /hammerspoon
Staggeringly powerful macOS desktop automation with Lua
★ 16,430⑂ 739👁 121⑃ 1,157● 2,632▤ 103
+2
Daily
16,430
stars
739
forks
121
watchers
1,157
prs
2,632
issues
103
releases
README
Hammerspoon Discord: Click to join What is Hammerspoon? This is a tool for powerful automation of OS X. At its core, Hammerspoon is just a bridge between the operating system and a Lua scripting engine. What gives Hammerspoon its power is a set of extensions that expose specific pieces of system functionality, to the user. With these, you can write Lua scripts to control many aspects of your OS X environment. How do I install it? Manually Download the latest release Drag Hammerspoon.app from your Downloads folder to Applications Homebrew brew install hammerspoon --cask What next? Out of the box, Hammerspoon does nothing - you will need to create ~/.hammerspoon/init.lua and fill it with useful code. There are several resources which can help you: Getting Started Guide API docs FAQ Sample Configurations supplied by various users Contribution Guide for developers looking to get involved An IRC channel for general chat/support/development (hammerspoon on Libera) Google Group for support What is the history of the project? Hammerspoon is a fork of Mjolnir. Mjolnir aims to be a very minimal application, with its extensions hosted externally and managed using a Lua package manager. We wanted to provide a more integrated experience. What is the future of the project? Our intentions for Hammerspoon broadly fall into these categories: Ever wider coverage of system APIs in Extensions Tighter integration between extensions Smoother user experience
Top issues
#3224hs.window:moveToScreen() behaves weirdly in macOS 12.4 when applied to a Google Chrome window.44 comments · 2022-05-31#2759Root causing our "weird" crash logs43 comments · 2021-03-11#370window:focus() focuses different window of app on same screen42 comments · 2015-07-06#2145Performance of loading docstrings41 comments · 2019-08-22#2215Create `hs.text` module to handle different string encodings37 comments · 2019-10-21#3306Keyboard input lag when running key listeners on macOS Ventura32 comments · 2022-10-29#2316moving/resizing electron based apps (slack, vscode)32 comments · 2020-03-09#3698hs.spaces.moveWindowToSpace does not work on macOS 15.0 Sequoia30 comments · 2024-10-06
Discussions
#3908safari-arc-kit: Arc-style tab switcher, command bar and hover sidebar for Safari0 comments · 2026-10-23#3898Menu bar icon + Xcode 270 comments · 2026-09-18#3874Hammerspoon23 comments · 2026-06-11#3853Added hammerspoon to macosWM.com, the macOS WM directory0 comments · 2026-03-08#3844Is Mac OS 13 REALLY necessary to use 1.1.0 ?0 comments · 2026-01-25#3840I build "Dictator" speech-to-text0 comments · 2026-01-06#3829Could anyone do a temporary built of the 1.0.0 with the 51 new commits included ?2 comments · 2025-10-20#3826A snippet to create app specific keybindings0 comments · 2025-09-26
Latest release
1.1.1 1.1.1 2026-02-26--- layout: post title: 1.1.1 permalink: /releasenotes/1.1.1.html --- Minimum macOS version: 13.0 Fixed - Download archive of Hammerspoon should no longer contain spurious resource forks that can confuse macOS Gatekeeper