Automate your macOS environment with Lua scripts.
Good to know
Requires ~/.hammerspoon/init.lua; does nothing until configured.
Unclaimed
Are you @Hammerspoon?Claim it, and your coding agent keeps it current with each release
Written by 
Are you @Hammerspoon?Claim it, and your coding agent keeps it current with each release
Thanks. Marked useful.
Thanks. The report went to osfeed, and the line gets checked against the repository.
Automate macOS windows, keyboard shortcuts, menus and devices with your own Lua scripts.
What you can do with Hammerspoon
Inspect and reposition application windows.
Good to know
Requires a Lua configuration.
Wrong?
Trigger Lua actions with global keyboard shortcuts.
Good to know
Requires a Lua configuration.
Wrong?
Create custom macOS menu bar items.
Good to know
Requires a Lua configuration.
Wrong?
Send HTTP requests from desktop automations.
Good to know
Requires a Lua configuration.
Wrong?
Inspect connected cameras and watch their properties.
Good to know
Requires a Lua configuration.
Wrong?
Configure and control an Elgato Stream Deck.
Good to know
Requires supported hardware; the official Elgato Stream Deck app must not be running.
Wrong?
Capture and manipulate images for scripted displays.
Good to know
Requires a Lua configuration.
Wrong?
Show all 47
Inspect and change system audio device settings.
Good to know
Requires a Lua configuration.
Wrong?
Trigger Lua callbacks from URLs and route web links.
Good to know
Requires a Lua configuration.
Wrong?
Read battery and power-source information.
Good to know
Unavailable information may return nil.
Wrong?
Calculate MD5, SHA and HMAC digests from data.
Good to know
Requires a Lua configuration.
Wrong?
Serve HTTP responses from Lua scripts.
Good to know
Requires a Lua configuration.
Wrong?
Inspect and change the mouse pointer position.
Good to know
Requires a Lua configuration.
Wrong?
Communicate with external devices over serial ports.
Good to know
Requires a serial device.
Wrong?
Present searchable choices in a graphical picker.
Good to know
Requires a Lua configuration.
Wrong?
Read and change system or named clipboards.
Good to know
Requires a Lua configuration.
Wrong?
Run callbacks when shared Lua values change.
Good to know
Requires a Lua configuration.
Wrong?
Display on-screen alerts from Lua scripts.
Good to know
Requires a Lua configuration.
Wrong?
Control Spotify playback from Lua scripts.
Good to know
Requires Spotify.
Wrong?
Trigger callbacks from Razer Tartarus V2 buttons and control its lighting.
Good to know
Only Razer Tartarus V2 is supported.
Wrong?
Send synchronous or asynchronous HTTP PUT requests.
Good to know
Requires a Lua configuration.
Wrong?
Handle mailto links with a Lua callback.
Good to know
Requires a Lua configuration.
Wrong?
Use a Stream Deck Mk2 for scripted controls.
Good to know
Requires a Stream Deck Mk2; quit the official Elgato app.
Wrong?
Read display information, including available hardware identifiers.
Good to know
Requires a Lua configuration.
Wrong?
Choose a toolbar style for scripted web views.
Good to know
Requires a Lua configuration.
Wrong?
Preserve a custom menu bar item's position across reloads.
Good to know
Set an autosave name for the menu item.
Wrong?
Find running applications by name or Lua pattern.
Good to know
Requires matching a running application.
Wrong?
Read an application's supported and preferred localizations.
Good to know
Requires a Lua configuration.
Wrong?
Submit chooser text even when it matches no listed choice.
Good to know
Enable the default-for-query option.
Wrong?
Read the current mouse cursor type.
Good to know
Requires a Lua configuration.
Wrong?
Read or set RTS and DTR serial control lines.
Good to know
Requires an open serial device that supports the relevant lines.
Wrong?
Use Stream Deck Mini V2, Plus and Pedal devices in Lua automations.
Good to know
Requires supported hardware; quit the official Elgato Stream Deck app.
Wrong?
Calculate MD5 and SHA digests as raw bytes for protocol integrations.
Good to know
Requires a Lua configuration.
Wrong?
Connect Lua automations to WebSocket services.
Good to know
Requires a reachable WebSocket service.
Wrong?
List files in a directory and its subdirectories with filtering options.
Good to know
Configure traversal and filtering through `hs.fs.fileListForPath()` options.
Wrong?
Hash files or successive data chunks, including SHA-3 and CRC32.
Good to know
CRC32 is a checksum; available algorithms are listed by `hs.hash.types`.
Wrong?
Read the artwork URL for the currently playing Spotify track.
Good to know
Requires Spotify; returns nil on error.
Wrong?
Run a watcher callback even when a value is assigned its existing value.
Good to know
Enable `alwaysNotify` for the watcher.
Wrong?
Read the original full URL in a URL event callback.
Good to know
Requires a Lua configuration.
Wrong?
Position an on-screen alert using a supplied window.
Good to know
Requires a Lua configuration.
Wrong?
Read and set the system trackpad tracking speed from Lua.
Good to know
Set the trackpad argument in `hs.mouse.trackingSpeed()`.
Wrong?
Read and toggle direct audio monitoring on supported audio devices.
Good to know
Requires hardware Thru support, such as a microphone with a headphone jack.
Wrong?
Generate smart-magnify gestures from a Lua automation.
Good to know
Requires a Lua configuration.
Wrong?
Handle web links handed off from native applications.
Good to know
Requires Hammerspoon to handle the incoming browsing activity.
Wrong?
Create, switch and remove macOS Spaces and move windows between them.
Good to know
Experimental private APIs and Accessibility actions; Mission Control may visibly open and Apple changes can break behavior.
Wrong?
Move floating windows into full-screen Spaces using the force option.
Good to know
Experimental API; forcing a move into a full-screen Space only works for floating windows.
Wrong?
Before you upgrade Hammerspoon
Newest firstUpgrade to macOS 13 or later before installing 1.1.0.
Read the evidence
Wrong?
Pass strings for every argument in `hs.task.new()`; convert numeric arguments with `tostring()` and handle nil on validation failure.
Read the evidence
Wrong?
URL scheme and host callback values are now lowercase; query parameter values are not changed by this fix.
Read the evidence
Wrong?
Show 5 older
Upgrade to macOS 12 or later before installing 1.0.0.
Read the evidence
Wrong?
Upgrade to macOS 11 or later before installing 0.9.98–0.9.100.
Read the evidence
Wrong?
Replace `hs.menubar.newWithPriority()` with `hs.menubar.new()`; remove `priority()` and `hs.menubar.priorities`. Use `autosaveName` to preserve a manually chosen position.
Read the evidence
Wrong?
Replace `hs.battery.psuSerial()` and `psuSerialString()` with `hs.battery.adapterSerialNumber()`; handle either a number, a string or nil.
Read the evidence
Wrong?
Console scrollback is now truncated; `hs.console.maxOutputHistory()` controls the history limit.
Read the evidence
Wrong?
Hammerspoon release history 8
Install the release archive without the stray resource forks that could confuse Gatekeeper.
Details
The download archive no longer includes the spurious resource forks described in the release notes.
Download 1.1.1; minimum macOS version is 13.0.
Now works: Automate your macOS environment with Lua scripts.
Seeded by @iluxav with Codex
Read the evidence
Set trackpad tracking speed from Lua.
Details
Adds trackpad speed control, direct audio monitoring and smart-magnify events; fixes WebSocket serving and window movement.
Download 1.1.0; requires macOS 13 or later.
Action required / inferredAction required / inferredBehavior changed / inferred: Trigger Lua callbacks from URLs and route web links.Now works: Serve HTTP responses from Lua scripts.Now works: Inspect and reposition application windows.Now works: Inspect and change the mouse pointer position.Added / inferred: Read and set the system trackpad tracking speed fro…Added / inferred: Read and toggle direct audio monitoring on supporte…Added / inferred: Generate smart-magnify gestures from a Lua automati…Added: Handle web links handed off from native application…Now works: Configure and control an Elgato Stream Deck.Now works: Automate your macOS environment with Lua scripts.
Seeded by @iluxav with Codex
Read the evidence
- Hammerspoon/hammerspoon/blob/1.1.0/Hammerspoon/Build%20Configs/Project-Base.xcconfig
- Hammerspoon/hammerspoon/releases/tag/1.1.0
- Hammerspoon/hammerspoon/blob/1.1.0/extensions/task/libtask.m
- Hammerspoon/hammerspoon/blob/1.1.0/extensions/urlevent/liburlevent.m
- Hammerspoon/hammerspoon/blob/1.1.0/extensions/mouse/libmouse.m
- Hammerspoon/hammerspoon/blob/1.1.0/extensions/audiodevice/libaudiodevice.m
- Hammerspoon/hammerspoon/blob/1.1.0/extensions/eventtap/libeventtap_event.m
- Hammerspoon/hammerspoon/pull/3635
Move windows between Spaces on macOS Sonoma 14.5.
Details
Restores Spaces window moves on Sonoma 14.5 and adds file enumeration, incremental hashes, Spotify artwork URLs and full URL callback data.
Download 1.0.0; requires macOS 12 or later.
Action required / inferredNow works: Create, switch and remove macOS Spaces and move win…Now works: Read battery and power-source information.Now works: Read and change system or named clipboards.Added / inferred: List files in a directory and its subdirectories wi…Added: Hash files or successive data chunks, including SHA…Added / inferred: Read the artwork URL for the currently playing Spot…Added / inferred: Run a watcher callback even when a value is assigne…Added / inferred: Read the original full URL in a URL event callback.Now works: Configure and control an Elgato Stream Deck.Added / inferred: Position an on-screen alert using a supplied window.Now works: Automate your macOS environment with Lua scripts.
Seeded by @iluxav with Codex
Read the evidence
- Hammerspoon/hammerspoon/blob/1.0.0/Hammerspoon/Build%20Configs/Project-Base.xcconfig
- Hammerspoon/hammerspoon/releases/tag/1.0.0
- Hammerspoon/hammerspoon/blob/1.0.0/extensions/fs/libfs.m
- Hammerspoon/hammerspoon/blob/1.0.0/extensions/hash/hash.lua
- Hammerspoon/hammerspoon/pull/3483
- Hammerspoon/hammerspoon/blob/1.0.0/extensions/spotify/spotify.lua
- Hammerspoon/hammerspoon/blob/1.0.0/extensions/watchable/watchable.lua
- Hammerspoon/hammerspoon/blob/1.0.0/extensions/urlevent/urlevent.lua
- Hammerspoon/hammerspoon/blob/1.0.0/extensions/alert/alert.lua
0.9.100
with 0.9.98, 0.9.99
with 0.9.98, 0.9.99
Keep custom menu bar items in their chosen positions across reloads.
Details
0.9.98 adds saved menu positions and more Stream Deck devices; 0.9.99 restores WebSocket connections; 0.9.100 adds binary digest output.
Download 0.9.100; requires macOS 11 or later.
Action requiredAdded / inferred: Preserve a custom menu bar item's position across r…Action required / inferredAction required / inferredNow works: Create, switch and remove macOS Spaces and move win…Added / inferred: Move floating windows into full-screen Spaces using…Now works: Inspect and reposition application windows.Now works: Capture and manipulate images for scripted displays.Now works / inferred: Inspect connected cameras and watch their propertie…Added / inferred: Find running applications by name or Lua pattern.Added / inferred: Read an application's supported and preferred local…Added / inferred: Submit chooser text even when it matches no listed…Added / inferred: Read the current mouse cursor type.Added / inferred: Read or set RTS and DTR serial control lines.Added: Use Stream Deck Mini V2, Plus and Pedal devices in…Added: Calculate MD5 and SHA digests as raw bytes for prot…Behavior changed: Automate your macOS environment with Lua scripts.Now works: Send HTTP requests from desktop automations.Added / inferred: Connect Lua automations to WebSocket services.
Seeded by @iluxav with Codex
Read the evidence
- Hammerspoon/hammerspoon/releases/tag/0.9.98
- Hammerspoon/hammerspoon/blob/0.9.98/extensions/menubar/libmenubar.m
- Hammerspoon/hammerspoon/compare/0.9.97...0.9.98
- Hammerspoon/hammerspoon/blob/0.9.98/extensions/spaces/libspaces.m
- Hammerspoon/hammerspoon/blob/0.9.98/extensions/camera/libcamera.m
- Hammerspoon/hammerspoon/blob/0.9.99/extensions/application/application.lua
- Hammerspoon/hammerspoon/blob/0.9.98/extensions/application/libapplication.m
- Hammerspoon/hammerspoon/blob/0.9.98/extensions/chooser/libchooser.m
- Hammerspoon/hammerspoon/blob/0.9.98/extensions/mouse/libmouse.m
- Hammerspoon/hammerspoon/blob/0.9.98/extensions/serial/libserial.m
- Hammerspoon/hammerspoon/releases/tag/0.9.100
- Hammerspoon/hammerspoon/releases/tag/0.9.99
- Hammerspoon/hammerspoon/issues/3422
0.9.97
with 0.9.96
with 0.9.96
Create, switch and remove macOS Spaces from Lua.
Details
0.9.96 adds experimental Spaces control; 0.9.97 fixes Docker-related Spaces errors and menu bar image positioning.
Download Hammerspoon 0.9.97 from its GitHub release.
Added / inferred: Create, switch and remove macOS Spaces and move win…Now works: Create, switch and remove macOS Spaces and move win…Now works: Create custom macOS menu bar items.Added / inferred: Read display information, including available hardw…Added / inferred: Choose a toolbar style for scripted web views.Action required / inferredAction required / inferred
Seeded by @iluxav with Codex
Read the evidence
Check whether a camera is in use without the fixed crash.
Details
Fixes camera usage checks and restores hs.automaticallyCheckForUpdates().
Download Hammerspoon 0.9.95 from its GitHub release.
Now works / inferred: Inspect connected cameras and watch their propertie…Now works / inferred: Automate your macOS environment with Lua scripts.
Seeded by @iluxav with Codex
Read the evidence
Trigger automations from a Razer Tartarus V2 keypad.
Details
Adds Razer Tartarus V2 support, Stream Deck Mk2 support, mailto handling and HTTP PUT requests.
Download Hammerspoon 0.9.94 from its GitHub release.
Added / inferred: Trigger callbacks from Razer Tartarus V2 buttons an…Added / inferred: Send synchronous or asynchronous HTTP PUT requests.Now works / inferred: Inspect and change system audio device settings.Now works / inferred: Inspect connected cameras and watch their propertie…Added / inferred: Handle mailto links with a Lua callback.Added / inferred: Use a Stream Deck Mk2 for scripted controls.Now works / inferred: Communicate with external devices over serial ports.
Seeded by @iluxav with Codex
Read the evidence
- Hammerspoon/hammerspoon/blob/0.9.94/extensions/razer/razer.lua
- Hammerspoon/hammerspoon/blob/0.9.94/extensions/http/http.lua
- Hammerspoon/hammerspoon/compare/0.9.93...0.9.94
- Hammerspoon/hammerspoon/blob/0.9.94/extensions/urlevent/urlevent.lua
- Hammerspoon/hammerspoon/blob/0.9.94/extensions/streamdeck/HSStreamDeckManager.m
0.9.93
Starting point
Starting point
Automate your Mac with Lua scripts that respond to desktop events.
Details
Existing capabilities before the ten-release window include window control, global shortcuts, menu items, device access and scripted notifications.
Historical baseline at 0.9.93; create ~/.hammerspoon/init.lua to configure automations.
Added: Automate your macOS environment with Lua scripts.Added: Inspect and reposition application windows.Added: Trigger Lua actions with global keyboard shortcuts.Added: Create custom macOS menu bar items.Added: Send HTTP requests from desktop automations.Added: Inspect connected cameras and watch their propertie…Added: Configure and control an Elgato Stream Deck.Added: Capture and manipulate images for scripted displays.Added: Inspect and change system audio device settings.Added: Trigger Lua callbacks from URLs and route web links.Added: Read battery and power-source information.Added: Calculate MD5, SHA and HMAC digests from data.Added: Serve HTTP responses from Lua scripts.Added: Inspect and change the mouse pointer position.Added: Communicate with external devices over serial ports.Added: Present searchable choices in a graphical picker.Added: Read and change system or named clipboards.Added: Run callbacks when shared Lua values change.Added: Display on-screen alerts from Lua scripts.Added: Control Spotify playback from Lua scripts.
Seeded by @iluxav with Codex
Read the evidence
- Hammerspoon/hammerspoon/blob/0.9.93/README.md
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/window/window.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/hotkey/hotkey.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/menubar/libmenubar.m
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/http/http.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/camera/libcamera.m
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/streamdeck/streamdeck.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/image/image.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/audiodevice/audiodevice.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/urlevent/urlevent.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/battery/battery.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/hash/libhash.m
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/httpserver/httpserver.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/mouse/mouse.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/serial/serial.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/chooser/chooser.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/pasteboard/pasteboard.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/watchable/watchable.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/alert/alert.lua
- Hammerspoon/hammerspoon/blob/0.9.93/extensions/spotify/spotify.lua