hammerspoon

Hammerspoon macOS Automation

Hammerspoon bridges macOS and Lua scripting for powerful desktop automation.

Directory Structure

~/.hammerspoon/
├── init.lua              # Main entry point (always loaded on startup)
├── Spoons/               # Plugin directory
│   └── *.spoon/          # Individual Spoon packages
│       └── init.lua      # Spoon entry point
└── .gitignore

Configuration Basics

init.lua - Entry Point

Hammerspoon always loads ~/.hammerspoon/init.lua on startup:

-- Enable CLI support (required for hs command)
require("hs.ipc")

-- Load a Spoon
hs.loadSpoon("SpoonName")

-- Configure the Spoon
spoon.SpoonName:bindHotkeys({...})

Loading Spoons

-- Load and auto-init (default)
hs.loadSpoon("MySpoon")

-- Load without global namespace
local mySpoon = hs.loadSpoon("MySpoon", false)

When loaded, Spoons are accessible via spoon.SpoonName.

CLI Usage (hs command)

Prerequisite: Add require("hs.ipc") to init.lua, then reload manually once.

# Reload configuration
hs -c 'hs.reload()'

# Show alert on screen
hs -c 'hs.alert("Hello from CLI")'

# Run any Lua code
hs -c 'print(hs.host.locale.current())'

# Get focused window info
hs -c 'print(hs.window.focusedWindow():title())'

Window Management with ShiftIt

ShiftIt is a popular Spoon for window tiling.

Installation

# Download from https://github.com/peterklijn/hammerspoon-shiftit
# Extract to ~/.hammerspoon/Spoons/ShiftIt.spoon/

Configuration

require("hs.ipc")
hs.loadSpoon("ShiftIt")

spoon.ShiftIt:bindHotkeys({
    -- Halves
    left = { { 'ctrl', 'cmd' }, 'left' },
    right = { { 'ctrl', 'cmd' }, 'right' },
    up = { { 'ctrl', 'cmd' }, 'up' },
    down = { { 'ctrl', 'cmd' }, 'down' },

    -- Quarters
    upleft = { { 'ctrl', 'cmd' }, '1' },
    upright = { { 'ctrl', 'cmd' }, '2' },
    botleft = { { 'ctrl', 'cmd' }, '3' },
    botright = { { 'ctrl', 'cmd' }, '4' },

    -- Other
    maximum = { { 'ctrl', 'cmd' }, 'm' },
    toggleFullScreen = { { 'ctrl', 'cmd' }, 'f' },
    center = { { 'ctrl', 'cmd' }, 'c' },
    nextScreen = { { 'ctrl', 'cmd' }, 'n' },
    previousScreen = { { 'ctrl', 'cmd' }, 'p' },
    resizeOut = { { 'ctrl', 'cmd' }, '=' },
    resizeIn = { { 'ctrl', 'cmd' }, '-' },
})

Modifier Keys

Key	Lua Name
Command	'cmd'
Control	'ctrl'
Option/Alt	'alt'
Shift	'shift'

Hotkey Binding (Without Spoons)

-- Simple hotkey
hs.hotkey.bind({'cmd', 'alt'}, 'R', function()
    hs.reload()
end)

-- Hotkey with message
hs.hotkey.bind({'cmd', 'shift'}, 'H', function()
    hs.alert.show('Hello!')
end)

Common Modules

hs.window - Window Management

-- Get focused window
local win = hs.window.focusedWindow()

-- Move/resize
win:moveToUnit('[0,0,0.5,1]')  -- Left half
win:maximize()
win:centerOnScreen()

-- Get all windows
local allWindows = hs.window.allWindows()

hs.application - App Control

-- Launch or focus app
hs.application.launchOrFocus('Safari')

-- Get running app
local app = hs.application.get('Finder')
app:activate()

hs.alert - On-screen Messages

hs.alert.show('Message')
hs.alert.show('Message', nil, nil, 3)  -- 3 second duration

hs.notify - System Notifications

hs.notify.new({title='Title', informativeText='Body'}):send()

hs.caffeinate - Sleep/Wake

-- Prevent sleep
hs.caffeinate.set('displayIdle', true)

-- Watch for sleep/wake events
hs.caffeinate.watcher.new(function(event)
    if event == hs.caffeinate.watcher.systemWillSleep then
        print('Going to sleep')
    end
end):start()

Spoons

What is a Spoon?

Self-contained Lua plugin with standard structure:

MySpoon.spoon/
└── init.lua     # Required: exports a table with methods

Official Spoon Repository

• Browse: https://www.hammerspoon.org/Spoons/
• Source: https://github.com/Hammerspoon/Spoons

SpoonInstall - Package Manager

hs.loadSpoon("SpoonInstall")

-- Install from official repo
spoon.SpoonInstall:andUse("ReloadConfiguration", {
    start = true
})

-- Install from custom repo
spoon.SpoonInstall.repos.Custom = {
    url = "https://github.com/user/repo",
    desc = "Custom spoons",
    branch = "main",
}
spoon.SpoonInstall:andUse("CustomSpoon", { repo = "Custom" })

Configuration Reloading

Manual Reload

• Click menubar icon -> "Reload Config"
• Or bind a hotkey:

hs.hotkey.bind({'cmd', 'alt', 'ctrl'}, 'R', function()
    hs.reload()
end)

Auto-reload on File Change

hs.loadSpoon("ReloadConfiguration")
spoon.ReloadConfiguration:start()

Or manually:

local configWatcher = hs.pathwatcher.new(os.getenv('HOME') .. '/.hammerspoon/', function(files)
    for _, file in pairs(files) do
        if file:sub(-4) == '.lua' then
            hs.reload()
            return
        end
    end
end):start()

CLI Reload

hs -c 'hs.reload()'

Note: Requires require("hs.ipc") in init.lua.

Troubleshooting

IPC Not Working

error: can't access Hammerspoon message port

Fix: Add require("hs.ipc") to init.lua and reload manually via menubar.

Spoon Not Loading

1. Check path: ~/.hammerspoon/Spoons/Name.spoon/init.lua
2. Check Lua syntax in Spoon's init.lua
3. Check Hammerspoon console for errors (menubar -> Console)

Hotkey Not Working

1. Check for conflicts with system shortcuts
2. Verify modifier key names are lowercase strings
3. Check console for binding errors

Console and Debugging

-- Print to console
print('Debug message')

-- Inspect objects
hs.inspect(someTable)

-- Open console
hs.openConsole()

Access console: Menubar icon -> Console (or Cmd+Alt+C if bound)

Best Practices

1. Always use IPC - Add require("hs.ipc") for CLI support
2. Use Spoons - Don't reinvent window management
3. Version control - Track ~/.hammerspoon/ with git
4. Capture variables - Objects not stored in variables get garbage collected
5. Check console - First place to look for errors

References

• Official Documentation
• Getting Started Guide
• Spoons Repository
• GitHub Repository