Creating Hammerspoon Scripts

Creating Hammerspoon Scripts

Status: Production Ready Last Updated: 2025-01-06 Dependencies: Hammerspoon installed on macOS Latest Versions: Hammerspoon 1.0.0+

Quick Start (5 Minutes)

1. Install Hammerspoon

Download from hammerspoon.org and move to /Applications. Grant Accessibility permissions when prompted.

2. Create Your Config File

# Create the config directory if it doesn't exist
mkdir -p ~/.hammerspoon

# Use the starter template
cp ~/.claude/skills/creating-hammerspoon-scripts/assets/templates/starter-init.lua ~/.hammerspoon/init.lua

3. Load and Test

Click the Hammerspoon menubar icon → "Reload Config". Test with Cmd+Alt+Ctrl+R to reload or Cmd+Alt+Left to move a window.

Why this matters:

• Config changes require explicit reload - this is the #1 gotcha
• The starter template includes essential patterns for all Hammerspoon configs
• Global hotkeys work anywhere in macOS for consistent automation

Decision Tree: Building Hammerspoon Scripts

User request → What are they trying to do?
    │
    ├─ Window Management
    │   ├─ Simple layouts (halves, quarters) → Use common_patterns.md patterns
    │   ├─ Multi-monitor → Use screen:next() pattern
    │   └─ Complex tiling → Build custom frame calculations
    │
    ├─ Hotkeys
    │   ├─ Single action → hs.hotkey.bind()
    │   ├─ Multiple related actions → Modal hotkey pattern
    │   └─ Context-specific → Window filter + modal
    │
    ├─ Application Control
    │   ├─ Launch/focus apps → hs.application.launchOrFocus()
    │   ├─ App launcher interface → Modal launcher pattern
    │   └─ Menu interactions → hs.application:selectMenuItem()
    │
    ├─ Event Watching
    │   ├─ File changes → hs.pathwatcher (MUST use global variable)
    │   ├─ WiFi/Network → hs.wifi.watcher (MUST use global variable)
    │   ├─ App events → hs.application.watcher (MUST use global variable)
    │   └─ USB devices → hs.usb.watcher (MUST use global variable)
    │
    ├─ UI Elements
    │   ├─ Temporary alerts → hs.alert.show()
    │   ├─ Notifications → hs.notify.new()
    │   ├─ Menubar items → hs.menubar.new()
    │   └─ On-screen drawing → hs.canvas or hs.drawing
    │
    └─ Troubleshooting
        ├─ "Config not working" → Did they reload? (hs.reload())
        ├─ "Watcher stopped" → Global variable issue
        ├─ "Hotkey doesn't work" → Key conflict or permissions
        └─ Check references/troubleshooting.md

Critical Rules

Always Do

✅ Store watchers in global variables - Not local. Prevents garbage collection.

-- GOOD
myWatcher = hs.pathwatcher.new(path, callback):start()

-- BAD - Will be garbage collected
local myWatcher = hs.pathwatcher.new(path, callback):start()

✅ Reload config after changes - Changes don't apply automatically

-- Essential reload hotkey - add to every config
hs.hotkey.bind({"cmd", "alt", "ctrl"}, "R", function()
  hs.reload()
end)

✅ Check for nil windows - Focused window can be nil

local win = hs.window.focusedWindow()
if not win then return end  -- Guard against nil

✅ Use screen:frame() not fullFrame() - Excludes menubar/dock for usable space

local screenFrame = win:screen():frame()  -- GOOD - Usable area

Never Do

❌ Never use local variables for watchers - They'll stop working after garbage collection

-- This will fail after a few minutes
local watcher = hs.pathwatcher.new(...):start()

❌ Never forget to reload config - Code changes have no effect until hs.reload()

❌ Never assume focused window exists - Always check for nil

❌ Never use :fullFrame() for window positioning - It includes menubar/dock, causing windows to go under them

Known Issues Prevention

This skill prevents 5 documented issues:

Issue #1: Watchers Stop Working After a Few Minutes

Error: Pathwatcher/wifi watcher/app watcher works initially then silently stops Source: Hammerspoon FAQ, GitHub issues #1234, #2567 Why It Happens: Lua garbage collector cleans up local variables when they go out of scope Prevention: This skill enforces global variable pattern for all watchers

-- WRONG - Gets garbage collected
local configWatcher = hs.pathwatcher.new(path, callback):start()

-- RIGHT - Persists for session lifetime
configWatcher = hs.pathwatcher.new(path, callback):start()

Issue #2: Config Changes Don't Apply

Error: User edits init.lua but nothing changes Source: Official Getting Started Guide, Stack Overflow #123456 Why It Happens: Config only loads on Hammerspoon launch or explicit reload Prevention: Skill templates include reload hotkey and auto-reload pattern

-- Manual reload hotkey (always include this)
hs.hotkey.bind({"cmd", "alt", "ctrl"}, "R", function() hs.reload() end)

-- Auto-reload on file save (optional but recommended)
function reloadConfig(files)
  local doReload = false
  for _, file in pairs(files) do
    if file:sub(-4) == ".lua" then doReload = true end
  end
  if doReload then hs.reload() end
end
configWatcher = hs.pathwatcher.new(os.getenv("HOME") .. "/.hammerspoon/", reloadConfig):start()

Issue #3: Hotkeys Don't Work or Trigger Wrong Actions

Error: Hotkey has no effect or activates system/app function instead Source: GitHub issues #3456, Hammerspoon docs Why It Happens: Key conflict with macOS or other apps Prevention: Skill provides conflict-free key combination patterns

• Use Cmd+Alt+Ctrl for global actions (rarely conflicts)
• Use Alt alone for modal entry (safe choice)
• Check System Settings → Keyboard → Keyboard Shortcuts

Issue #4: Windows Positioned Under Menubar or Dock

Error: Windows move to coordinates that put them partially off-screen Source: API documentation, GitHub issues #789 Why It Happens: Using :fullFrame() instead of :frame() Prevention: Skill patterns always use :frame() for usable screen area

-- WRONG - Includes menubar and dock area
local max = screen:fullFrame()

-- RIGHT - Only usable space
local max = screen:frame()

Issue #5: Modal Hotkeys Don't Exit

Error: Modal mode stays active after performing action Source: Common pattern mistake, Hammerspoon examples Why It Happens: Forgetting to call modal:exit() after action Prevention: Skill modal patterns always include explicit exit calls

-- WRONG - Modal stays active
appLauncher:bind("", "c", function()
  hs.application.launchOrFocus("Chrome")
  -- Missing modal:exit()
end)

-- RIGHT - Modal exits after launching
appLauncher:bind("", "c", function()
  hs.application.launchOrFocus("Chrome")
  appLauncher:exit()  -- Always exit
end)

Common Patterns

Pattern 1: Window to Left Half

function moveWindowLeftHalf()
  local win = hs.window.focusedWindow()
  if not win then return end

  local screen = win:screen()
  local frame = screen:frame()

  win:setFrame({
    x = frame.x,
    y = frame.y,
    w = frame.w / 2,
    h = frame.h
  })
end

hs.hotkey.bind({"cmd", "alt"}, "Left", moveWindowLeftHalf)

When to use: Basic window tiling, side-by-side workflows

Pattern 2: Modal App Launcher

local appLauncher = hs.hotkey.modal.new()

-- Define apps
local apps = {
  c = "Google Chrome",
  f = "Finder",
  t = "iTerm",
  s = "Slack"
}

-- Bind each app
for key, appName in pairs(apps) do
  appLauncher:bind("", key, function()
    hs.application.launchOrFocus(appName)
    appLauncher:exit()
  end)
end

-- Exit on Escape
appLauncher:bind("", "escape", function()
  appLauncher:exit()
end)

-- Global hotkey to enter modal
hs.hotkey.bind({"alt"}, "space", function()
  appLauncher:enter()
end)

When to use: Quick app switching, avoiding complex key chords

Pattern 3: Auto-Reload Configuration

function reloadConfig(files)
  local doReload = false
  for _, file in pairs(files) do
    if file:sub(-4) == ".lua" then
      doReload = true
    end
  end
  if doReload then
    hs.reload()
  end
end

-- MUST be global variable
configWatcher = hs.pathwatcher.new(os.getenv("HOME") .. "/.hammerspoon/", reloadConfig):start()
hs.alert.show("Config loaded")

When to use: Development workflow, frequent config changes

Pattern 4: Multi-Monitor Window Movement

function moveWindowToNextScreen()
  local win = hs.window.focusedWindow()
  if not win then return end

  local nextScreen = win:screen():next()
  win:moveToScreen(nextScreen)
end

hs.hotkey.bind({"cmd", "alt"}, "N", moveWindowToNextScreen)

When to use: Multi-monitor setups, presentations

Using Bundled Resources

References (references/)

Load these as needed for detailed information:

• references/hammerspoon_reference_cheat_sheet.md - Comprehensive API reference - Complete Hammerspoon API documentation with all modules, functions, and examples (use for deep API questions)

  API Index (138 modules):

  • Window Management: hs.window, hs.window.filter, hs.window.highlight, hs.window.layout, hs.window.switcher, hs.window.tiling, hs.grid, hs.layout, hs.expose, hs.hints, hs.tabs
  • Application Control: hs.application, hs.application.watcher, hs.appfinder
  • Hotkeys & Input: hs.hotkey, hs.hotkey.modal, hs.eventtap, hs.eventtap.event, hs.keycodes, hs.mouse, hs.noises
  • Screen & Display: hs.screen, hs.screen.watcher, hs.brightness, hs.spaces, hs.spaces.watcher
  • Audio: hs.audiodevice, hs.audiodevice.datasource, hs.audiodevice.watcher, hs.sound, hs.speech, hs.speech.listener
  • Watchers: hs.pathwatcher, hs.battery.watcher, hs.caffeinate.watcher, hs.wifi.watcher, hs.usb.watcher, hs.pasteboard.watcher, hs.uielement.watcher, hs.watchable
  • UI Elements: hs.alert, hs.menubar, hs.canvas, hs.canvas.matrix, hs.chooser, hs.console, hs.dialog, hs.dialog.color, hs.drawing, hs.drawing.color, hs.notify, hs.styledtext, hs.dockicon
  • Network: hs.network, hs.network.configuration, hs.network.host, hs.network.ping, hs.network.ping.echoRequest, hs.network.reachability, hs.wifi, hs.bonjour, hs.bonjour.service
  • Web & HTTP: hs.http, hs.httpserver, hs.httpserver.hsminweb, hs.socket, hs.socket.udp, hs.websocket, hs.webview, hs.webview.datastore, hs.webview.toolbar, hs.webview.usercontent
  • System: hs.battery, hs.caffeinate, hs.host, hs.host.locale, hs.location, hs.location.geocoder, hs.brightness, hs.camera, hs.crash, hs.settings, hs.sharing, hs.osascript, hs.applescript, hs.urlevent
  • File System: hs.fs, hs.fs.volume, hs.fs.xattr, hs.pathwatcher, hs.plist
  • Accessibility: hs.axuielement, hs.axuielement.axtextmarker, hs.axuielement.observer, hs.uielement
  • Media Integration: hs.spotify, hs.itunes, hs.vox, hs.deezer
  • Hardware: hs.usb, hs.usb.watcher, hs.serial, hs.midi, hs.hid, hs.hid.led, hs.streamdeck, hs.razer, hs.tangent, hs.milight
  • Utilities: hs.fnutils, hs.geometry, hs.hash, hs.base64, hs.json, hs.inspect, hs.image, hs.logger, hs.math, hs.timer, hs.timer.delayed, hs.task, hs.ipc, hs.utf8, hs.sqlite3
  • Documentation: hs.doc, hs.doc.builder, hs.doc.hsdocs, hs.doc.markdown, hs.spoons
  • Advanced: hs.distributednotifications, hs.javascript, hs.pasteboard, hs.redshift, hs.spotlight, hs.spotlight.group, hs.spotlight.item, hs.shortcuts, hs.messages, hs.mjomatic

• references/api_quick_reference.md - Most-used Hammerspoon API functions organized by category

• references/common_patterns.md - Complete window management, modal, and watcher patterns

• references/troubleshooting.md - Solutions for all common issues

When to load these: User asks for API details, needs complex patterns, or encounters issues. Start with the comprehensive reference for detailed API questions, use quick reference for common operations

Assets (assets/)

Complete templates and snippets for immediate use:

Templates:

• assets/templates/starter-init.lua - Full featured starter config (~100 lines)
• assets/templates/minimal-init.lua - Bare minimum to get started (~20 lines)

Snippets:

• assets/snippets/window-management.lua - Halves, quarters, maximize, multi-monitor
• assets/snippets/modal-launcher.lua - Complete app launcher modal
• assets/snippets/auto-reload.lua - Pathwatcher auto-reload
• assets/snippets/watchers.lua - WiFi, app, and USB watcher examples

When to use: User needs complete working code, wants to copy-paste, or is starting fresh

The 3-Step Process for Any Hammerspoon Task

Step 1: Identify the Pattern

Match user request to one of these categories:

• Window management → Frame calculation
• Hotkeys → Global or modal binding
• App control → Launch/focus/menu
• Events → Watcher with global variable
• UI → Alert/notification/menubar

Step 2: Use Proven Pattern

• Check common_patterns.md for the specific pattern
• Or use appropriate assets/snippets/ file
• Adapt to user's specific needs

Step 3: Apply Critical Rules

• Watchers → Global variable
• Windows → Nil check
• Config → Reload mechanism
• Modals → Exit calls

Troubleshooting

Problem: "My watcher worked then stopped"

Solution: Check if it's stored in a global variable. Remove local keyword.

-- Change this:
local myWatcher = ...

-- To this:
myWatcher = ...

Problem: "Hotkey doesn't work"

Solution:

1. Check Hammerspoon console for errors (hs.toggleConsole())
2. Try different key combination (avoid system shortcuts)
3. Verify Accessibility permissions in System Settings

Problem: "Config changes have no effect"

Solution: Reload config using Cmd+Alt+Ctrl+R hotkey or menubar → "Reload Config"

Problem: "Windows go under menubar/dock"

Solution: Use screen:frame() not screen:fullFrame()

Dependencies

Required:

• Hammerspoon 1.0.0+ (macOS 11.0+)
• Accessibility permissions enabled

Optional:

• None - Hammerspoon is self-contained

Official Documentation

• Hammerspoon: https://www.hammerspoon.org/
• API Docs: http://www.hammerspoon.org/docs/
• Getting Started: https://www.hammerspoon.org/go/
• Spoons Repository: https://www.hammerspoon.org/Spoons/

Complete Setup Checklist

• Hammerspoon installed in /Applications
• Accessibility permissions granted
• ~/.hammerspoon/init.lua created
• Reload hotkey added (Cmd+Alt+Ctrl+R)
• Config successfully loads (test with reload)
• All watchers use global variables (no local keyword)
• Window operations include nil checks
• Modal hotkeys include exit() calls

Questions? Issues?

1. Check references/troubleshooting.md for detailed solutions
2. Verify all critical rules are followed
3. Test in Hammerspoon console (hs.toggleConsole())
4. Check official docs: https://www.hammerspoon.org/docs/