macwatcher.spoon

MacWatcher is a Hammerspoon Spoon for macOS that executes commands in response to system events. It is aimed at users who already run Hammerspoon and want shell scripts or binaries to fire automatically when the machine changes state. Supported triggers, as described in the README: - Resume from sleep or unlock (whenResume), with an optional delay before the command runs. - Going to sleep or locking (whenSuspend), which can run immediately before the event. - WiFi network changes (onWifiChange); the SSID is appended as an argument to the command. - Light/dark appearance changes (onThemeChange), including changes that occurred while the machine was asleep; the value "light" or "dark" is appended as an argument. - A synchronous teardown hook (whenStop) that runs when stop() is called. Configuration options include a cooldown period (minimum seconds between hook executions) and a task timeout for command execution. Commands are executed asynchronously with timeouts, and each hook accepts a delay parameter. Installation paths covered by the README: downloading the release zip and placing the MacWatcher.spoon folder in ~/.hammerspoon/Spoons/, installing via SpoonInstall from the release zip URL, or cloning the repository directly into the Spoons directory for development. After installation, Hammerspoon must be reloaded. Usage is through Lua configuration: load the Spoon with hs.loadSpoon("MacWatcher"), optionally set cooldown and taskTimeout, register hooks with the chained methods shown above, then call start(). Full API reference is published on GitHub Pages. The project is MIT licensed.