hammerspoon

Host scope: mini/macOS. Keep this skill disabled on joi/Linux; shared source may remain in the repository. Do not sync activation links between hosts or switch to SSH merely because the local host lacks Hammerspoon. Remote actions follow the session's host-authorization policy.

One-off action = one hs -q -c '<lua>' call. Lasting behavior (hotkeys, watchers, menubar) = a module in ~/.hammerspoon/. Recipes: REFERENCE.md.

Readiness

hs -q -c 'return "ok"' must print ok. If not:

• exit 69 / "can't access message port" → Hammerspoon not running (open -a Hammerspoon) or hs.ipc not loaded → ensure require("hs.ipc") is in ~/.hammerspoon/init.lua; the pathwatcher auto-reloads config, retry after ~2s.
• hs binary missing → tell the user to run hs.ipc.cliInstall("/opt/homebrew") in the Hammerspoon console.
• Window/app calls silently no-op → hs -c 'return hs.accessibilityState()' must be true; if false, user grants it in System Settings → Privacy & Security → Accessibility.

One-off mode