MacWatcher Spoon

A Hammerspoon Spoon that executes commands on system events like wake, sleep, and WiFi changes.

Features

• Execute commands when resuming from sleep/unlock
• Trigger actions when system goes to sleep/locks
• Monitor WiFi network changes
• React to light/dark appearance changes, including ones crossed while asleep
• Configurable execution delays and cooldown periods
• Async command execution with timeouts

Installation

Ensure you have Hammerspoon installed, then choose a method:

Release zip (recommended)

1. Download MacWatcher.spoon.zip from the latest release
2. Unzip — this produces a MacWatcher.spoon folder
3. Move it to ~/.hammerspoon/Spoons/
4. Reload Hammerspoon (menu bar icon → Reload Config, or run hs.reload() in the console)

SpoonInstall (if you already use it)

spoon.SpoonInstall:installSpoonFromZip(
  "https://github.com/hugoh/MacWatcher.spoon/releases/latest/download/MacWatcher.spoon.zip"
)

Clone from git (for development or latest changes)

cd ~/.hammerspoon/Spoons
git clone https://github.com/hugoh/MacWatcher.spoon.git

Configuration

-- Load and configure the Spoon
local macWatcher = hs.loadSpoon("MacWatcher")

-- Configure default settings (optional)
macWatcher.cooldown = 30         -- Minimum seconds between hook executions
macWatcher.taskTimeout = 30      -- Timeout for command execution

-- Set up event hooks
macWatcher
  :whenResume({"/bin/echo", "System resumed"}, 2)   -- Run 2 seconds after a session is resumed
  :whenSuspend({"/usr/bin/true"}, 0)                -- Run immediately before sleep
  :onWifiChange({"/usr/local/bin/ssid_handler"}, 1) -- Run 1s after WiFi change (SSID appended as argument)
  :onThemeChange({"/usr/local/bin/theme_handler"})  -- Run on light/dark change and on wake ("light"/"dark" appended as argument)
  :whenStop({"/usr/local/bin/teardown"})            -- Run synchronously when stop() is called

-- Start monitoring
macWatcher:start()

-- Run suspend and whenStop hooks when Hammerspoon quits or reloads
hs.shutdownCallback = function() macWatcher:stop() end

API documentation

Full API reference is available at https://macwatcher-spoon.larve.net/.