Hammerspoon configuration skill

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)