hammerspoon

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

hs -q -c 'hs.application.launchOrFocus("Obsidian") return "ok"'
hs -q -t 15 -c '<anything touching AppleScript or many windows>'   # default IPC timeout is 4s; busy main loop can also cause one-off "receive timeout" — retry