hammerspoon

Overview

Manage Hammerspoon configuration for macOS automation including app launching, window switching, emoji/symbol pickers, and leader modal. Window management is handled by AeroSpace.

Configuration locations

• Config directory: ~/.config/hammerspoon/
• Symlink: ~/.hammerspoon → ~/.config/hammerspoon/
• CLI tool: hs (installed via hs.ipc.cliInstall() in init.lua)

Current modules

Core infrastructure

hyper-key.lua - Inline hyper key implementation

• No spoon dependencies
• Provides HyperKey.new(mods) constructor
• Binding methods: bind(key):toFunction(name, fn) and bind(key):toApplication(app)
• Tracks bindings in self.bindings table

init.lua - Main entry point

• Calls hs.ipc.cliInstall() to enable CLI access
• Defines hyper modifier: {cmd, ctrl, alt, shift}
• Loads window-switcher and sets up cmd+space and cmd+tab bindings
• Loads notch-clock with 4-minute offset
• Loads leader modal with emoji and symbol pickers

Leader modal system

leader-modal.lua - Modal keybinding system

• Timeout-based modal (default 3000ms)
• Shows on-screen hints for available bindings
• Supports nested leader keys
• Sticky mode for repeated actions

leader-dsl.lua - DSL for defining leader bindings

• Leader(key, description, bindings) - Define leader menu
• Bind(key, description, action, options) - Define action
• Actions can be functions, shell commands, or mode transitions
• Automatically registers clues from ~/.config/hammerspoon/clues/ directory

clues/*.lua - Leader binding definitions

• windows.lua - Window management (moved to AeroSpace)
• hammerspoon.lua - Reload config, console, update apps, switcher
• apps.lua - App launching
• system.lua - System operations
• cleanshot.lua - CleanShot integration
• emoji.lua - Emoji picker
• superwhisper.lua - SuperWhisper integration

Pickers

emoji-picker.lua - Emoji chooser

• Fuzzy-searchable emoji picker
• Categories and descriptions
• Inserts selected emoji via keystroke

symbol-picker.lua - Symbol chooser

• Special characters and symbols
• Categories: arrows, math, punctuation, currency, etc.
• Inserts selected symbol via keystroke

chooser-style.lua - Shared chooser styling

• Dark theme
• Consistent width and row count
• Applied to all choosers

Window switcher

window-switcher.lua - Unified launcher/dispatcher modal

• Uses hs.chooser API with fuzzy matching
• Shows windows, apps, and commands
• Keybindings: cmd+space and cmd+tab
• Dark theme with 15 visible rows

fuzzy.lua - Dynamic programming fuzzy matching

• Subsequence matching with scoring bonuses
• Type priority: window (3), app (2), command (1)

notch-clock.lua - Clock in notch area

• Shows time in MacBook notch
• 4-minute offset configuration

Common operations

Using the hs CLI

The hs command-line tool provides direct interaction with Hammerspoon. It requires hs.ipc.cliInstall() to be called in init.lua (already configured).

Check for errors and module status:

echo "
local status = {modules_loaded = {}, errors = {}}
local modules = {'hyper-key', 'config-watch', 'window-hotkeys', 'quick-switch', 'window-switcher'}
for _, mod in ipairs(modules) do
  local ok, result = pcall(require, mod)
  if ok then
    table.insert(status.modules_loaded, mod)
  else
    table.insert(status.errors, mod .. ': ' .. tostring(result))
  end
end
return hs.json.encode(status, true)
" | hs -c ''

View live console output:

hs -C

Execute Hammerspoon commands:

echo "hs.alert.show('test')" | hs -c ''
echo 'hs.reload()' | hs -c ''

Interactive Lua REPL:

hs

Mirror prints to console:

hs -P

Run a script:

hs /path/to/script.lua

Common flags:

• -A - Auto-launch Hammerspoon if not running
• -C - Clone console prints to this terminal (best for checking errors)
• -P - Mirror prints to Hammerspoon console
• -c - Execute command and return result
• -i - Force interactive mode
• -n - Disable colorized output
• -N - Force colorized output
• -q - Quiet mode (errors and results only)

Other operations

Reload Hammerspoon:

echo 'hs.reload()' | hs -c ''
# or via URL:
open -g hammerspoon://reload

Check if running:

ps aux | rg -i hammerspoon

Open console window:

open "hammerspoon://consoleWindow"

Test configuration: Edit any .lua file in ~/.config/hammerspoon/ to trigger auto-reload

Development patterns

Adding new leader bindings

Create a file in ~/.config/hammerspoon/clues/:

return Leader("key", "Description", {
  Bind("a", "Action 1", { fn = function() ... end }),
  Bind("b", "Action 2", { shell = "/path/to/script" }),
  Bind("c", "Action 3", { mode = "mode_name" }),
})

Creating new modules

1. Create ~/.config/hammerspoon/module-name.lua
2. Return module table or functionality
3. Require in init.lua: local module = require("module-name")

App replacement status

Current Hammerspoon setup replaces:

• AltTab: Window switching via window-switcher.lua (cmd+space, cmd+tab)

Other macOS automation tools:

• Karabiner-Elements: Key remapping (caps lock to ctrl, etc.)
• AeroSpace: Window management (tiling, workspaces, monitor assignment)
• CleanShot: Screenshots (integrated via leader modal)

Troubleshooting

Check for errors

Use the hs CLI to check for module loading errors:

echo "
local status = {modules_loaded = {}, errors = {}}
local modules = {'hyper-key', 'config-watch', 'window-hotkeys', 'quick-switch', 'window-switcher'}
for _, mod in ipairs(modules) do
  local ok, result = pcall(require, mod)
  if ok then
    table.insert(status.modules_loaded, mod)
  else
    table.insert(status.errors, mod .. ': ' .. tostring(result))
  end
end
return hs.json.encode(status, true)
" | hs -c ''

Or view live console output: hs -C

Config not loading

• Check symlink: ls -la ~/.hammerspoon
• Verify Hammerspoon is running: ps aux | rg Hammerspoon
• Reload manually: echo 'hs.reload()' | hs -c ''
• Check for errors: hs -C or open "hammerspoon://consoleWindow"

Keybindings not working

• Check for conflicts with app shortcuts
• Verify modifier keys are correct
• Test with: echo "hs.alert.show('test')" | hs -c ''

Auto-reload not triggering

• Verify config-watch.lua is loaded in init.lua
• Check file extension is .lua
• Restart Hammerspoon app

CLI not working

If hs command not found, ensure hs.ipc.cliInstall() is called in init.lua

Philosophy

Zero spoons approach

• Inline functionality instead of external dependencies
• Only use spoons if absolutely necessary
• Keep implementation simple and maintainable

Decision criteria for using spoons:

• Must provide significant value that's hard to inline
• Must be actively maintained
• Must be worth the workflow complexity

Future spoon management (not yet implemented): If spoons are needed, they will be managed via GitHub workflow:

1. Add spoon commit hash to .github/workflows/versions.lua
2. Create .github/workflows/hammerspoon.yml build workflow
3. Workflow clones spoons at specified revisions, bundles into tarball
4. Release as hammerspoon-YYYY.MM.DD-darwin-arm64.tar.gz
5. Only add spoons to config after workflow builds successfully

This ensures pinned, reproducible spoon dependencies similar to other tools in the repo.

File organization

• One module per file
• Clear, descriptive names
• Require modules in init.lua
• Use XDG-style config directory

Resources

• Hammerspoon API: https://www.hammerspoon.org/docs/
• Plan document: ~/.claude/plans/hammerspoon-consolidation.md
• dbalatero dotfiles: https://github.com/dbalatero/dotfiles/tree/main/hammerspoon (reference only)