Hammerspoon
Powerful macOS automation tool using Lua scripting
Quick Take: Hammerspoon
Hammerspoon is the ultimate power tool for macOS automation — but only for people willing to write code. If you're a developer who wants complete, unrestricted control over your operating system's behavior, nothing else comes close. The Wi-Fi watchers, USB callbacks, custom menu bar widgets, and programmable window management let you build a Mac experience that's exactly tailored to how you work. The barrier is Lua scripting, but for anyone comfortable with code, that's not a barrier — it's the feature.
Best For
- •Developers who want programmable window management
- •Power users who've outgrown Raycast and Rectangle
- •Automation enthusiasts building context-aware workflows
- •Anyone who wants their Mac to adapt to their environment automatically
Install with Homebrew
brew install --cask hammerspoonWhat is Hammerspoon?
Hammerspoon is a macOS automation tool that lets you control nearly every aspect of your operating system through Lua scripts. Window management, hotkeys, application launching, file watching, Wi-Fi event handling, USB device detection, clipboard monitoring, menu bar widgets — anything the macOS API exposes, Hammerspoon can script. It sits in your menu bar, loads a Lua config file, and bridges your scripts to native macOS APIs through a well-documented set of modules. The typical Hammerspoon user is someone who outgrew the capabilities of Raycast, Rectangle, or BetterTouchTool and wanted something fully programmable. Maybe you need a hotkey that launches a specific app, resizes its window to the right half of your external monitor, and hides all other windows. Maybe you want your Mac to automatically mute when it joins your office Wi-Fi network. Maybe you want a menu bar indicator that shows how many unread Slack messages you have. Hammerspoon can do all of this — but you have to write the Lua code yourself. This is simultaneously Hammerspoon's greatest strength and its biggest barrier to entry. There's no GUI for configuration. There are no presets you click to enable. You write code in a ~/.hammerspoon/init.lua file, and when you save it, Hammerspoon reloads and executes it. For developers, this is liberating — you have complete control with no artificial limits. For non-programmers, it's a brick wall. Hammerspoon is not a product; it's a platform. And for the right user, it's the most powerful tool on their Mac.
Deep Dive: Hammerspoon's Bridge Between Lua and macOS
How Hammerspoon exposes macOS system APIs to Lua scripts, and why that architecture enables automation that no other tool can match.
History & Background
Hammerspoon was forked from Mjolnir, an earlier macOS automation framework created by Steven Degutis around 2014. Mjolnir provided the core idea — bridge Lua to macOS APIs — but was modular to the point of being difficult to use (you had to install individual modules for basic functionality). Hammerspoon bundled the most popular modules into a single application with a cohesive API, making it immediately usable out of the box. The fork happened in 2014, and Hammerspoon has been actively maintained since, with the current maintainer Chris Jones (cmsj) leading development.
How It Works
Hammerspoon embeds a Lua 5.4 interpreter and registers Objective-C/Swift extensions as Lua modules. When you call `hs.window.focusedWindow()`, the Lua runtime calls into an Objective-C function that uses the macOS Accessibility API to query the window server. The result is wrapped back into a Lua table. This bridge architecture means any macOS API can potentially be exposed as a Hammerspoon module. The hs.eventtap module, for example, provides raw access to the macOS event system — you can intercept and modify keyboard and mouse events at the system level.
Ecosystem & Integrations
The Spoon ecosystem is Hammerspoon's answer to plugin management. Spoons are self-contained Lua modules with standardized metadata (name, version, description, download URL). The SpoonInstall Spoon acts as a package manager — you declare dependencies in your init.lua, and it downloads and loads them automatically. Popular Spoons include WindowHalfsAndThirds (window management), Seal (a launcher), EmmyLua (IDE autocomplete annotations), and AClock (a simple analog clock in the menu bar).
Future Development
Hammerspoon's development is community-driven with no commercial roadmap. Current priorities include maintaining compatibility with the latest macOS versions (Apple frequently changes Accessibility API behavior), improving the documentation with more tutorials and examples, and expanding the Spoon ecosystem. There's ongoing discussion about adding Swift-based modules for better performance in CPU-intensive tasks, though Lua's lightweight nature means most automations run instantaneously.
Key Features
Window Management via Code
Hammerspoon's hs.window module provides complete programmatic control over any window on your screen. Move, resize, maximize, minimize, center, snap to grid, send to another monitor — all through Lua functions. Unlike Rectangle (which maps fixed shortcuts to fixed layouts), Hammerspoon lets you define custom logic: 'If this app is focused AND I press this key combo, then resize to this exact frame on this specific display.' Users build highly personalized window management systems that no GUI tool can replicate.
System-Wide Hotkeys
Define hotkeys that work globally across macOS. Bind any key combination to any Lua function. Common uses: launching apps (faster than Spotlight), toggling VPN connections, opening specific URLs, running shell commands, or triggering complex multi-step workflows. Hotkeys can be modal — activate a 'mode' with one key, then use a second key to pick an action, like Vim's command mode for your desktop.
Wi-Fi, USB, and Hardware Event Callbacks
Hammerspoon can watch for hardware events and trigger actions automatically. The hs.wifi.watcher module fires callbacks when your Wi-Fi SSID changes — useful for muting speakers when you arrive at the office. The hs.usb.watcher module detects when USB devices connect or disconnect — automatically launch your audio app when you plug in your DAC. The hs.battery.watcher monitors power state changes. These event-driven automations run silently in the background.
Custom Menu Bar Widgets
Build custom menu bar items using hs.menubar. Display text, icons, or both. Click handlers open submenus or trigger actions. Developers use this to show build status from CI/CD pipelines, display current VPN status, show the number of open pull requests, or create quick-access menus for their most common scripts. You control what the menu item shows and what happens when you interact with it.
Application Watching and Control
The hs.application.watcher module notifies you when applications launch, hide, unhide, activate, deactivate, or quit. You can build rules like 'When Zoom launches, automatically mute my Spotify' or 'When Slack activates, move it to my secondary monitor.' This turns your Mac into a context-aware workspace that adapts to what you're doing.
URL Dispatching
Hammerspoon can register itself as a URL handler for custom schemes. Click a hammerspoon:// URL from any app, and it triggers a Lua function. This is useful for integrating Hammerspoon automations with external tools — click a link in your task manager to set up your workspace for that project, or create Slack webhooks that trigger local scripts.
Who Should Use Hammerspoon?
1The Multi-Monitor Developer
Working with a MacBook and two external displays, this developer has a precise layout for each activity. When coding, the editor goes on the center monitor, terminal on the right, browser on the left. When in meetings, Zoom goes center, notes app right, Slack left. They write Hammerspoon functions for each layout and bind them to Ctrl+1 (coding layout) and Ctrl+2 (meeting layout). One keypress rearranges everything. Rectangle can't do conditional placement across three specific monitors; Hammerspoon can.
2The Context-Aware Automator
This developer wants their Mac to behave differently based on location. At home (detected via Wi-Fi SSID), the audio output routes to their USB speakers and Bluetooth connects to their ergonomic mouse. At the office, the audio mutes (no one wants to hear your notifications), the VPN connects automatically, and Slack moves to a specific window position. All of this happens silently through Hammerspoon's Wi-Fi and USB watchers — no manual setup when switching locations.
3The Keyboard-Driven Power User
This user refuses to touch the mouse for anything that can be done with the keyboard. They've built a Hammerspoon 'hyper key' (Caps Lock remapped via Karabiner Elements to Cmd+Ctrl+Alt+Shift) that unlocks a secondary layer of shortcuts. Hyper+E launches VS Code. Hyper+T opens Ghostty. Hyper+B launches the browser. Hyper+M maximizes the current window. Hyper+Left/Right snaps windows to halves. Their entire workflow is instant and muscle memory.
How to Install Hammerspoon on Mac
Hammerspoon is available as a Homebrew cask. Configuration is done by editing a Lua file.
Install via Homebrew
Run `brew install --cask hammerspoon`. This installs the application and places it in /Applications.
Grant Accessibility Permissions
On first launch, macOS will ask you to grant Hammerspoon Accessibility access in System Settings > Privacy & Security > Accessibility. This is required for window management and hotkey functionality.
Create Your Config
Create the file `~/.hammerspoon/init.lua`. This is your main configuration. Start with something simple: `hs.hotkey.bind({'cmd', 'alt'}, 'R', function() hs.reload() end)` — this binds Cmd+Alt+R to reload your config.
Explore the API
Open the Hammerspoon console (click the menu bar icon > Console) and type Lua commands interactively. Use `hs.window.focusedWindow():frame()` to see the current window's position and size. The console is the best way to experiment before committing code to your config.
Pro Tips
- • Start with the 'Getting Started' guide on hammerspoon.org — it walks through window management basics in 10 minutes.
- • Install a Spoon (Hammerspoon's plugin system) for common use cases: SpoonInstall, Seal (a launcher), and WindowHalfsAndThirds are popular starting points.
- • Use `hs.alert.show('Hello')` for quick visual feedback when debugging your scripts.
Configuration Tips
Build a Hyper Key Setup
Combine Hammerspoon with Karabiner-Elements: use Karabiner to remap Caps Lock to Cmd+Ctrl+Alt+Shift (the 'hyper' modifier that nothing else uses). Then in Hammerspoon, bind hyper+letter combinations to your most common actions. You get a full layer of custom shortcuts that never conflict with any application's built-in keys.
Use the Spoon Plugin System
Spoons are pre-built Hammerspoon modules that you can install and configure. Instead of writing window management from scratch, install the 'WindowHalfsAndThirds' Spoon and configure it in three lines. Browse available Spoons at hammerspoon.org/Spoons/ — there are dozens covering common use cases.
Alternatives to Hammerspoon
Hammerspoon is the most powerful automation tool for macOS, but most people don't need that much power. Here are alternatives for different levels of automation.
Raycast
Raycast is a GUI-first productivity tool with extensions, AI chat, window management, and clipboard history — all configured through a graphical interface. If you want 80% of Hammerspoon's functionality without writing code, Raycast is the answer. The tradeoff: Raycast can't do event-driven automation (Wi-Fi callbacks, USB watchers), can't create custom menu bar items, and can't implement conditional logic that Hammerspoon handles effortlessly.
Rectangle
Rectangle is a free, focused window manager with keyboard shortcuts for halves, thirds, quarters, and monitors. If window management is all you need, Rectangle does it in 30 seconds with zero configuration. Hammerspoon is for when you need window management AND custom logic — 'put this specific app on this specific monitor at this specific size when I press this key.'
Karabiner-Elements
Karabiner-Elements remaps keys and creates complex keyboard modifications. Hammerspoon can do key remapping too, but Karabiner is more precise for low-level key manipulation (like turning Caps Lock into a Hyper key). The best setup: use Karabiner for key remapping and Hammerspoon for everything those keys trigger. They complement each other perfectly.
Shortcuts (Apple)
Apple's Shortcuts app provides a visual automation builder that integrates with many apps. It's easier to learn but far more limited — it can't manage windows, can't watch hardware events, and its macOS integration is still rough compared to iOS. Hammerspoon is more capable but requires code.
Pricing
Hammerspoon is 100% free and open source under the MIT License. There are no paid tiers, no premium modules, and no telemetry. Development is driven by volunteers and the project accepts donations through GitHub Sponsors. The Lua scripting language is also free and open source.
Pros
- ✓Complete programmatic control over macOS through Lua
- ✓Extremely powerful window management with custom logic
- ✓Event-driven automation (Wi-Fi, USB, battery, app lifecycle)
- ✓Custom menu bar widgets for any data source
- ✓Spoon plugin system for reusable modules
- ✓Interactive console for testing and debugging
- ✓Completely free and open source
- ✓Tiny resource footprint — runs silently in the background
Cons
- ✗Requires writing Lua code — no GUI configuration at all
- ✗Steep learning curve for non-programmers
- ✗Documentation is reference-style, not tutorial-style
- ✗Some APIs can break across macOS versions (especially Accessibility)
- ✗Smaller community compared to tools like Raycast or Alfred
- ✗No built-in AI features or natural language commands
Community & Support
Hammerspoon has a passionate if niche community. The GitHub repository (github.com/Hammerspoon/hammerspoon) has over 12,000 stars, making it one of the most popular macOS automation tools. The mailing list and GitHub Discussions are the primary support channels. The API documentation on hammerspoon.org is comprehensive but dense — it reads like a reference manual, not a tutorial. The best learning resource is browsing other users' init.lua configs shared on GitHub (search 'hammerspoon dotfiles'). The Spoon ecosystem provides curated, tested modules for common tasks.
Frequently Asked Questions about Hammerspoon
Our Verdict
Hammerspoon is the ultimate power tool for macOS automation — but only for people willing to write code. If you're a developer who wants complete, unrestricted control over your operating system's behavior, nothing else comes close. The Wi-Fi watchers, USB callbacks, custom menu bar widgets, and programmable window management let you build a Mac experience that's exactly tailored to how you work. The barrier is Lua scripting, but for anyone comfortable with code, that's not a barrier — it's the feature.
About the Author
Productivity & Workflow Analyst
Related Technologies & Concepts
Related Topics
macOS Automation
Tools for automating workflows and system behavior on macOS.
Sources & References
Fact-CheckedLast verified: Feb 23, 2026
- 1Hammerspoon Official Website
Accessed Feb 23, 2026
Research queries: Hammerspoon Mac 2026 automation Lua