# Hammerspoon Published January 1, 2026 · Updated August 10, 2026 Powerful macOS automation tool using Lua scripting Category: System Utilities · Free · Replaces Keyboard Maestro ($36) · [Official website](https://www.hammerspoon.org) ## Install with Homebrew `brew install --cask hammerspoon` ## Quick take Free Lua automation still actively updated (1.1.1 in Feb 2026). Best for programmers; Keyboard Maestro/Raycast for zero-code users. 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 ## What is Hammerspoon? August 2026 status: Hammerspoon is actively maintained. **1.1.1** released 26 February 2026 (after **1.1.0** on 24 December 2025), requiring **macOS 13.0+**. It remains free/open source Lua automation for window management, hotkeys, device callbacks and system events on Apple Silicon and Intel Macs. 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 capable tool on their Mac. ## Features - **Hammerspoon 1.1.x Maintenance (2025, 2026).** The 1.1.0/1.1.1 releases fix Gatekeeper-confusing resource forks in download archives, improve hs.window.filter PID tracking, Stream Deck Mini callbacks, Handoff URL handling and several crash cases after apps terminate. Minimum macOS is 13.0, upgrade if you are still on ancient 0.9 builds. - **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. ## How to Install Hammerspoon on Mac Hammerspoon is available as a Homebrew cask. Configuration is done by editing a Lua file. 1. **Install via Homebrew.** Run `brew install --cask hammerspoon`. This installs the application and places it in /Applications. 2. **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. 3. **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. 4. **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. ## Pros - Complete programmatic control over macOS through Lua - Extremely capable 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 ## Closer look: 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. ## FAQ ### What is the latest Hammerspoon version in 2026? 1.1.1 (26 February 2026) per official release notes, with macOS 13.0 as the minimum system version. ### Do I need to know Lua? You need basic programming skills, but Lua is one of the simplest languages to pick up. If you can read Python or JavaScript, you can write Lua in an afternoon. Hammerspoon configs are typically 50-200 lines of straightforward code, not complex software engineering. Start by copying examples from the Getting Started guide and modifying them. ### How does Hammerspoon compare to AppleScript or Shortcuts? AppleScript is Apple's built-in scripting language and Shortcuts is their visual automation tool. Both are more limited than Hammerspoon. AppleScript can't manage windows reliably, can't watch hardware events and has verbose, awkward syntax. Shortcuts is visual and easy but lacks low-level macOS access. Hammerspoon sits below both, it talks directly to macOS APIs and can do things neither Apple tool can. ### Will Hammerspoon slow down my Mac? No. Hammerspoon uses around 20-40MB of RAM at idle and negligible CPU. The Lua scripts execute instantly when triggered. It's one of the lightest automation tools available, far lighter than Raycast or Alfred. ### Can Hammerspoon replace Raycast? Technically, yes, you can build a launcher, clipboard manager and window manager entirely in Hammerspoon. But it would take significant effort to replicate what Raycast offers out of the box. Most power users run both: Raycast for its GUI features (quick launcher, extension store, AI chat) and Hammerspoon for event-driven automations and custom logic that Raycast can't do. ### Does it work on Apple Silicon Macs? Yes. Hammerspoon runs natively on Apple Silicon (M1, M2, M3, M4) without Rosetta. All system APIs work correctly on the new architecture. ### What's a Spoon? A Spoon is Hammerspoon's plugin format, a reusable Lua module packaged with metadata and documentation. Spoons handle common tasks like window management, emoji input, clipboard filtering and application switching. You install them by downloading the.spoon file and loading it in your init.lua. Think of them as community-maintained 'recipes' that save you from writing common automations from scratch. ## Sources - [Hammerspoon](https://www.hammerspoon.org/) - [Release notes](https://www.hammerspoon.org/releasenotes/) - [GitHub releases](https://github.com/Hammerspoon/hammerspoon/releases) - [Spoons](https://www.hammerspoon.org/Spoons/) - [API docs](https://www.hammerspoon.org/docs/) - [1.1.1 notes](https://www.hammerspoon.org/releasenotes/1.1.1.html) - [Homebrew hammerspoon cask](https://formulae.brew.sh/cask/hammerspoon) - [Hammerspoon automation overview](https://lifetips.alibaba.com/tech-efficiency/hammerspoon-is-capable-free-automation-tool-for-os-x) ## Related - [Maccy](https://bundl.run/apps/maccy) - [Stats](https://bundl.run/apps/stats) - [SuperWhisper](https://bundl.run/apps/superwhisper) - [MacWhisper](https://bundl.run/apps/macwhisper) - [HyperWhisper](https://bundl.run/apps/hyperwhisper) - [Aqua Voice](https://bundl.run/apps/aqua-voice) - [Hammerspoon vs Keyboard Maestro](https://bundl.run/compare/hammerspoon-vs-keyboard-maestro) - [Free alternative to Keyboard Maestro](https://bundl.run/https:/) ```json { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://bundl.run/#organization", "name": "Bundl.run", "url": "https://bundl.run", "logo": { "@type": "ImageObject", "url": "https://bundl.run/og-image.png", "width": 1200, "height": 630 }, "description": "The Ninite for Mac. Install all your essential Mac apps with one terminal command.", "sameAs": [ "https://github.com/abhiofficial/bundl-mac-setup", "https://x.com/bundlrun", "https://www.producthunt.com/products/bundl-run" ], "foundingDate": "2024", "contactPoint": { "@type": "ContactPoint", "contactType": "customer support", "url": "https://bundl.run/faq" } }, { "@type": "WebSite", "@id": "https://bundl.run/#website", "name": "Bundl.run", "url": "https://bundl.run", "description": "The Ninite for Mac. Install all your essential Mac apps with one terminal command.", "publisher": { "@id": "https://bundl.run/#organization" }, "inLanguage": "en-US" }, { "@type": "Person", "@id": "https://bundl.run/authors/jordan-kim#person", "name": "Jordan Kim", "jobTitle": "Productivity & Workflow Analyst", "url": "https://bundl.run/authors/jordan-kim", "worksFor": { "@id": "https://bundl.run/#organization" }, "description": "Jordan Kim focuses on productivity software, system utilities, and workflow optimization tools. With a background in operations management and process improvement, Jordan evaluates how well applications integrate into daily workflows and enhance overall productivity. Jordan tests each tool across multiple use cases—from solo work to team collaboration—documenting setup complexity, learning curves, and long-term value. A certified project management professional with experience at Fortune 500 companies, Jordan brings rigorous methodology to software evaluation.", "knowsAbout": [ "Productivity Applications", "Note-Taking & Knowledge Management", "Task & Project Management", "Communication Tools", "System Utilities", "Workflow Automation" ], "image": "https://bundl.run/authors/jordan-kim.svg" }, { "@type": "BreadcrumbList", "@id": "https://bundl.run/apps/hammerspoon#breadcrumb", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://bundl.run" }, { "@type": "ListItem", "position": 2, "name": "Apps", "item": "https://bundl.run/apps" }, { "@type": "ListItem", "position": 3, "name": "Hammerspoon", "item": "https://bundl.run/apps/hammerspoon" } ] }, { "@type": "WebPage", "@id": "https://bundl.run/apps/hammerspoon", "url": "https://bundl.run/apps/hammerspoon", "name": "Hammerspoon for Mac", "description": "Powerful macOS automation tool using Lua scripting", "isPartOf": { "@id": "https://bundl.run/#website" }, "publisher": { "@id": "https://bundl.run/#organization" }, "inLanguage": "en-US", "datePublished": "2026-01-01T00:00:00Z", "dateModified": "2026-08-10T13:34:04.000Z", "author": { "@id": "https://bundl.run/authors/jordan-kim#person" }, "mainEntity": { "@id": "https://bundl.run/apps/hammerspoon#software" }, "breadcrumb": { "@id": "https://bundl.run/apps/hammerspoon#breadcrumb" } }, { "@type": "SoftwareApplication", "@id": "https://bundl.run/apps/hammerspoon#software", "name": "Hammerspoon", "description": "Powerful macOS automation tool using Lua scripting", "applicationCategory": "UtilitiesApplication", "operatingSystem": "macOS", "url": "https://bundl.run/apps/hammerspoon", "image": { "@type": "ImageObject", "url": "https://img.logo.dev/hammerspoon.org", "caption": "Hammerspoon app icon for Mac" }, "sameAs": [ "https://www.hammerspoon.org/", "https://formulae.brew.sh/cask/hammerspoon" ], "review": { "@type": "Review", "author": { "@id": "https://bundl.run/authors/jordan-kim#person" }, "reviewBody": "Free Lua automation still actively updated (1.1.1 in Feb 2026). Best for programmers; Keyboard Maestro/Raycast for zero-code users." }, "about": { "@type": "Thing", "name": "Hammerspoon", "description": "Powerful macOS automation tool using Lua scripting" }, "isPartOf": { "@id": "https://bundl.run/#website" } }, { "@type": "Article", "@id": "https://bundl.run/apps/hammerspoon#article", "headline": "Hammerspoon for Mac — Full Review & Installation Guide 2026", "description": "Free Lua automation still actively updated (1.1.1 in Feb 2026). Best for programmers; Keyboard Maestro/Raycast for zero-code users.", "image": "https://img.logo.dev/hammerspoon.org", "author": { "@id": "https://bundl.run/authors/jordan-kim#person" }, "publisher": { "@id": "https://bundl.run/#organization" }, "datePublished": "2026-01-01T00:00:00Z", "dateModified": "2026-08-10T13:34:04.000Z", "mainEntityOfPage": { "@type": "WebPage", "@id": "https://bundl.run/apps/hammerspoon" }, "articleSection": "UtilitiesApplication", "speakable": { "@type": "SpeakableSpecification", "cssSelector": [ "h1", ".key-facts" ] }, "about": { "@type": "SoftwareApplication", "name": "Hammerspoon", "url": "https://bundl.run/apps/hammerspoon" }, "mentions": [ { "@type": "SoftwareApplication", "name": "Keyboard Maestro" } ] }, { "@type": "FAQPage", "@id": "https://bundl.run/apps/hammerspoon#faq", "mainEntity": [ { "@type": "Question", "name": "What is the latest Hammerspoon version in 2026?", "acceptedAnswer": { "@type": "Answer", "text": "1.1.1 (26 February 2026) per official release notes, with macOS 13.0 as the minimum system version." } }, { "@type": "Question", "name": "Do I need to know Lua?", "acceptedAnswer": { "@type": "Answer", "text": "You need basic programming skills, but Lua is one of the simplest languages to pick up. If you can read Python or JavaScript, you can write Lua in an afternoon. Hammerspoon configs are typically 50-200 lines of straightforward code, not complex software engineering. Start by copying examples from the Getting Started guide and modifying them." } }, { "@type": "Question", "name": "How does Hammerspoon compare to AppleScript or Shortcuts?", "acceptedAnswer": { "@type": "Answer", "text": "AppleScript is Apple's built-in scripting language and Shortcuts is their visual automation tool. Both are more limited than Hammerspoon. AppleScript can't manage windows reliably, can't watch hardware events and has verbose, awkward syntax. Shortcuts is visual and easy but lacks low-level macOS access. Hammerspoon sits below both, it talks directly to macOS APIs and can do things neither Apple tool can." } }, { "@type": "Question", "name": "Will Hammerspoon slow down my Mac?", "acceptedAnswer": { "@type": "Answer", "text": "No. Hammerspoon uses around 20-40MB of RAM at idle and negligible CPU. The Lua scripts execute instantly when triggered. It's one of the lightest automation tools available, far lighter than Raycast or Alfred." } }, { "@type": "Question", "name": "Can Hammerspoon replace Raycast?", "acceptedAnswer": { "@type": "Answer", "text": "Technically, yes, you can build a launcher, clipboard manager and window manager entirely in Hammerspoon. But it would take significant effort to replicate what Raycast offers out of the box. Most power users run both: Raycast for its GUI features (quick launcher, extension store, AI chat) and Hammerspoon for event-driven automations and custom logic that Raycast can't do." } }, { "@type": "Question", "name": "Does it work on Apple Silicon Macs?", "acceptedAnswer": { "@type": "Answer", "text": "Yes. Hammerspoon runs natively on Apple Silicon (M1, M2, M3, M4) without Rosetta. All system APIs work correctly on the new architecture." } }, { "@type": "Question", "name": "What's a Spoon?", "acceptedAnswer": { "@type": "Answer", "text": "A Spoon is Hammerspoon's plugin format, a reusable Lua module packaged with metadata and documentation. Spoons handle common tasks like window management, emoji input, clipboard filtering and application switching. You install them by downloading the.spoon file and loading it in your init.lua. Think of them as community-maintained 'recipes' that save you from writing common automations from scratch." } } ], "isPartOf": { "@id": "https://bundl.run/apps/hammerspoon" } } ] } ```