Tools · SPBoucher
Menu

Hammerspoon

by Hammerspoon contributors · Application

Open-source macOS automation app that exposes system APIs to a Lua configuration file for hotkeys, window management and event-driven scripts

MIT licenseOpen sourceFreeLocalSelf-hostable
Visit official site Compare

Link verified Nov 2, 2026

Overview

Hammerspoon is an open-source macOS automation tool (MIT license) that acts as a bridge between the operating system and an embedded Lua interpreter. It does nothing until the user writes ~/.hammerspoon/init.lua; from there, Lua code can bind global hotkeys, move and resize windows, react to application, screen, Wi-Fi, USB, battery or filesystem events, draw on-screen overlays, control audio devices, read the clipboard, run shell commands and AppleScript, and expose a menu-bar item or a local URL/IPC endpoint.

The extension modules are documented API by API, and reusable plug-ins called Spoons package common setups such as window grids or caffeine toggles. Because everything is text, configurations are easy to version-control and share, which appeals to developers who want programmable, keyboard-driven control of their Mac without a GUI macro editor.

It is distributed as a signed app from GitHub releases (also via Homebrew cask), requires Accessibility permission, and supports recent macOS versions on Intel and Apple Silicon. Limits: Lua is a prerequisite, there is no visual editor, and features depending on private or changing macOS APIs can break between OS releases.

Capabilities

  • Global hotkeys and key remapping in Lua
  • Window placement and multi-display management
  • Watchers for application, screen, Wi-Fi, USB, battery and path events
  • Menu-bar items, alerts and on-screen drawing
  • Shell, AppleScript and URL-scheme integration
  • Reusable Spoon plug-ins

Typical workflows

  1. Tile windows with keyboard shortcuts
  2. Switch audio output or Wi-Fi settings when a display connects
  3. Trigger scripts from a URL scheme or another app

Strengths

  • Fully scriptable and version-controllable configuration
  • Free and MIT-licensed
  • Broad coverage of macOS APIs in one tool

Limitations

  • Requires writing Lua
  • No graphical macro editor
  • Some modules depend on APIs that change across macOS releases

Prerequisites

  • Recent macOS release
  • Accessibility permission for the app

Who it is for

  • Developers and power users who prefer code to GUIs
  • Keyboard-centric window-management enthusiasts

Alternatives & comparison

  • Alfred

    macOS launcher and productivity app whose paid Powerpack adds workflows, clipboard history, snippets and custom searches

    ProprietaryFreemium
  • AppleScript

    Apple's English-like scripting language that drives scriptable macOS applications through Apple events, run from Script Editor, osascript or other automation tools

    ProprietaryFree
  • Automator

    Apple's long-standing drag-and-drop workflow builder for macOS that produces apps, Quick Actions, folder actions and calendar-triggered automations

    ProprietaryFree
  • cliclick

    Small open-source macOS command-line tool that emulates mouse clicks, drags, movements, key presses and typing for scripted GUI control

    Open sourceOpen source
  • Karabiner-Elements

    Free, public-domain keyboard customizer for macOS that remaps keys and defines complex modifications through JSON rules at the driver level

    Open sourceOpen source
  • Keyboard Maestro

    Commercial macOS macro application that runs sequences of actions from hotkeys, typed strings, application, time, device and system triggers

    ProprietaryPaid
  • Raycast

    Extensible launcher for macOS (with Windows and iOS versions) combining app search, clipboard history, snippets, window management and a store of community extensions

    MixedFreemium
  • Shortcuts

    Apple's built-in visual automation app for macOS, iOS and iPadOS that chains app actions, scripts and system functions into runnable shortcuts

    ProprietaryFree
Compare Hammerspoon with its alternatives →

Sources & verification

Primary sources consulted for this record. Claims are tied to the fields each source supports; the automated link checker re-verifies every URL on a schedule.

Confidence
High
Reviewed
Nov 1, 2026
Links
Verified · Nov 2, 2026

Spotted an error?

Broken link, outdated license, wrong category, or a tool that no longer exists? Tell us; reports are reviewed by the editor.

launchd

Apple Inc. · macOS automation

In-depth entry

macOS's built-in service manager that starts, supervises and schedules daemons and per-user agents from property-list job definitions

ProprietaryFreeLocalBroken

Shortcuts

Apple Inc. · macOS automation

Apple's built-in visual automation app for macOS, iOS and iPadOS that chains app actions, scripts and system functions into runnable shortcuts

ProprietaryFreeLocalNov 2, 2026

cliclick

Carsten Blüm (BlueM) · macOS automation

Small open-source macOS command-line tool that emulates mouse clicks, drags, movements, key presses and typing for scripted GUI control

BSD-3-ClauseOpen sourceFreeLocalMaintenanceNov 2, 2026

Automator

Apple Inc. · macOS automation

Apple's long-standing drag-and-drop workflow builder for macOS that produces apps, Quick Actions, folder actions and calendar-triggered automations

ProprietaryFreeLocalMaintenanceNov 2, 2026