workshop

hammerspoon/

Lua scripts for Hammerspoon — macOS automation triggered by system events, hotkeys, and login hooks.

Hotkeys

Shortcut	Context	Description
⌘⇧T	Finder frontmost	Open current Finder folder in iTerm2 (if installed) or Terminal
⌘↩	Finder frontmost	Open selected item (cmd+o)
⌃L	Global	Lock screen
⌘⌥P	Global	Play a sound (media/attention cue)

⌘⌥S (save picture of selected area as a file) and ⌘⌥R (screenshot and recording options) are not handled here right now — see the note in modules/hotkeys.lua and ../macos/bettermouse/README.md for why.

Setup

setup.sh installs Hammerspoon with Homebrew if it isn’t already in /Applications, then creates the symlink below. After a fresh install, open Hammerspoon once and grant it Accessibility access in System Settings → Privacy & Security. Its hotkeys don’t fire without it.

If you already have a Hammerspoon config that isn’t in the repo yet, setup won’t overwrite it. Move it into the repo by hand first, then symlink so Hammerspoon can still find it at the path it expects:

# 1. Copy your existing init.lua into the repo first
cp ~/.hammerspoon/init.lua ~/Documents/.../hammerspoon/init.lua

# 2. Delete the original
rm -rf ~/.hammerspoon

# 3. Symlink the repo folder to where Hammerspoon expects its config
ln -s ~/Documents/.../hammerspoon ~/.hammerspoon

Then reload Hammerspoon from the menu bar icon. From this point all changes are version controlled — Hammerspoon reads directly from the repo via the symlink.