# Hammerspoon/hammerspoon

Staggeringly powerful macOS desktop automation with Lua

Repository: https://github.com/Hammerspoon/hammerspoon
Canonical: https://ross.abutalabs.com/products/hammerspoon
Homepage: http://www.hammerspoon.org
Language: Objective-C
License: MIT
License Family: permissive
Topics: macos, objective-c, lua, hammerspoon, osx, automation, mjolnir, irc
Last push: 2026-07-08T21:13:24+00:00

## Health v2 (maintenance only)
Score: 82/100 (v2, computed 2026-09-03T02:20:16.233290+00:00)
- activity 91, release rhythm 60, longevity 100
- inputs: {"age_days": 4347, "days_push": 56, "days_rel": 188, "gap_med": 63, "n_releases_24m": 2}
- flags: none
- formula: round(0.45*activity + 0.35*rhythm + 0.20*longevity); archived -> min(score, 10)

## Adoption (not part of the score)
Stars 15999, forks 712 (observed 2026-08-28T04:11:14.636630+00:00)

## What it is
Hammerspoon is a macOS desktop automation application that bridges the operating system's APIs to a Lua scripting engine. Users write Lua configuration scripts to control windows, applications, keyboard/mouse events, and many other system functions.

## Use cases
- automate window management on macOS
- bind custom keyboard shortcuts to system actions
- run scripts when wifi connects to a network
- show alerts when battery drops below a threshold
- control mouse and keyboard events programmatically
- watch for application launch and quit events
- script macOS accessibility APIs

## When to choose
- you want deep, scriptable automation of macOS with Lua
- you need fine-grained control over windows, hotkeys, and system events
- you prefer a free, open-source alternative to paid Mac automation tools
- you want to extend functionality with community Spoons or your own modules

## When to avoid
- you need a no-code automation tool with a GUI
- you want cross-platform automation beyond macOS
- you are not comfortable writing and maintaining Lua scripts
- you only need simple app launching that Spotlight already covers

## Facets
- artifact type: application
- maturity: active
- function: developer-tools, workflow-automation, plugin-system, gui
- domain: developer-tools, desktop-applications
- platform: lua
- tags: lua-scripting, desktop-automation, window-management, keyboard-shortcuts, hotkeys, accessibility-api, spoons, automation, macos, desktop

## Member repositories
- Hammerspoon/hammerspoon (main) score 82

## Provenance
- Observed fields: from GitHub, fetched 2026-08-28T04:11:14.636630+00:00.
- Health v2: computed from the inputs above; adoption is never an input.
- Inferred fields (summary, facets, guidance): AI-extracted, prompt v1, taxonomy v1, on 2026-08-29T17:05:17.553562+00:00, confidence not recorded.
  - readme: https://github.com/Hammerspoon/hammerspoon (fetched 2026-08-28T04:11:14.636630+00:00, sha 0141bb95d176)
  - homepage: http://www.hammerspoon.org (fetched 2026-08-29T08:03:07.148576+00:00, sha 3e96f7b0bdc9)
  - site_page: http://www.hammerspoon.org/docs/index.html (fetched 2026-08-29T08:03:07.185237+00:00, sha d9c64a687dc9)
  - site_page: http://www.hammerspoon.org/docs (fetched 2026-08-29T08:03:07.233467+00:00, sha 2d782bfa5bc7)
  - site_page: http://www.hammerspoon.org/faq (fetched 2026-08-29T08:03:07.152162+00:00, sha 273743d6bfe0)
- Data as of 2026-08-30T08:39:29.467469+00:00.