# Hammerspoon — Staggeringly Powerful macOS Automation with Lua

> An open-source macOS tool that bridges Lua scripting to system APIs, enabling custom window management, hotkeys, app launching, Wi-Fi triggers, and more.

## Install

Save in your project root:

# Hammerspoon — Staggeringly Powerful macOS Automation with Lua

## Quick Use
```bash
brew install --cask hammerspoon
# Create ~/.hammerspoon/init.lua:
hs.hotkey.bind({"cmd","alt"}, "H", function()
  local win = hs.window.focusedWindow()
  win:moveToUnit(hs.layout.left50)
end)
# Reload config: Cmd+Alt+R (after binding it)
```

## Introduction
Hammerspoon is a macOS automation tool that exposes system-level APIs to a Lua scripting environment. It replaces multiple single-purpose utilities by letting you write short scripts for window management, application control, file watching, network events, and virtually any other macOS interaction.

## What Hammerspoon Does
- Manages window positions and sizes with Lua functions
- Binds global hotkeys to arbitrary actions
- Watches for Wi-Fi, USB, screen, and battery events
- Controls audio devices, volume, and playback
- Provides a built-in IPC mechanism and HTTP server for external integration

## Architecture Overview
Hammerspoon embeds a LuaJIT interpreter inside a native Objective-C application. System functionality is exposed through extension modules (hs.window, hs.screen, hs.application, etc.) that wrap Cocoa and Carbon APIs. When the user edits init.lua and reloads, Hammerspoon re-evaluates the script, registers hotkeys and event watchers, and keeps the Lua VM running in the background.

## Self-Hosting & Configuration
- Install via Homebrew: `brew install --cask hammerspoon` or download from the website
- Grant Accessibility permissions when prompted on first launch
- All configuration lives in `~/.hammerspoon/init.lua`
- Install community Spoons (plugin bundles) via SpoonInstall or manually
- Reload configuration instantly from the menu bar icon or a bound hotkey

## Key Features
- Scriptable access to nearly every macOS system API
- Spoons plugin system for reusable, shareable configuration modules
- Built-in console for interactive Lua experimentation
- Event watchers for Wi-Fi SSID changes, USB connect/disconnect, and screen layout changes
- URL scheme handler for triggering actions from external tools or scripts

## Comparison with Similar Tools
- **Karabiner-Elements** — Focused on keyboard remapping only; Hammerspoon covers broader automation
- **BetterTouchTool** — GUI-driven input customization with paid license; less scriptable
- **Raycast** — App launcher with extensions; Hammerspoon is lower-level and fully code-driven
- **Shortcuts (macOS)** — Apple's visual automation; limited system-level access compared to Hammerspoon
- **AppleScript/JXA** — Built-in macOS scripting; slower and less ergonomic for system-level tasks

## FAQ
**Q: Do I need to know Lua?**
A: Basic Lua is easy to pick up, and the Hammerspoon API documentation includes copy-paste examples. Most configurations are under 50 lines.

**Q: What are Spoons?**
A: Spoons are self-contained plugin modules that package reusable Hammerspoon functionality. Examples include window layout managers, app watchers, and clipboard tools.

**Q: Does Hammerspoon affect system performance?**
A: Hammerspoon uses minimal resources when idle. Event watchers and hotkey listeners are passive; CPU usage only spikes briefly when a script action executes.

**Q: Can Hammerspoon control apps that don't support AppleScript?**
A: Yes. Hammerspoon uses the Accessibility API, which works with any app that exposes standard UI elements, regardless of AppleScript support.

## Sources
- https://github.com/Hammerspoon/hammerspoon
- https://www.hammerspoon.org/

---
Source: https://tokrepo.com/en/workflows/asset-0e3aeb5f
Author: AI Open Source