MacWatcher v1.5.3

A Hammerspoon Spoon that runs commands on system events: wake, sleep, and WiFi changes.

GitHub Latest release

Overview

Download: https://github.com/hugoh/MacWatcher.spoon/releases/latest

Variables

MacWatcher.cooldown Variable #

Minimum seconds between repeated hook executions for the same event (default: 30). A resume or suspend always runs if the other one fired since.

MacWatcher.taskTimeout Variable #

Maximum seconds a command may run before it is forcibly terminated (default: 30).

Methods

MacWatcher:whenResume(cmd[, delay]) → MacWatcher Method #

Register a command to run after the system resumes from sleep or unlocks.

Parameters

  • cmd - A table where the first element is the executable path and remaining elements are arguments
  • delay - (optional) Seconds to wait before executing; default 0

Returns

  • The MacWatcher object, for method chaining
MacWatcher:whenSuspend(cmd[, delay]) → MacWatcher Method #

Register a command to run before the system sleeps or locks.

Parameters

  • cmd - A table where the first element is the executable path and remaining elements are arguments
  • delay - (optional) Seconds to wait before executing; default 0

Returns

  • The MacWatcher object, for method chaining
MacWatcher:onWifiChange(cmd[, delay]) → MacWatcher Method #

Register a command to run when the WiFi network changes. The current SSID is appended as an extra argument to the command.

Parameters

  • cmd - A table where the first element is the executable path and remaining elements are arguments
  • delay - (optional) Seconds to wait before executing; default 0

Returns

  • The MacWatcher object, for method chaining
MacWatcher:onThemeChange(cmd[, delay]) → MacWatcher Method #

Register a command to run when the light/dark appearance changes, or when the system wakes (a scheduled appearance switch that occurs while asleep fires no live notification, so wake re-checks it too). The current appearance ("light" or "dark") is appended as an extra argument to the command.

Parameters

  • cmd - A table where the first element is the executable path and remaining elements are arguments
  • delay - (optional) Seconds to wait before executing; default 0

Returns

  • The MacWatcher object, for method chaining
MacWatcher:whenStop(cmd) → MacWatcher Method #

Register a command to run synchronously when stop() is called. Useful for teardown scripts that must complete before the process exits.

Parameters

  • cmd - A table where the first element is the executable path and remaining elements are arguments

Returns

  • The MacWatcher object, for method chaining
MacWatcher:init() Method #

Called automatically by hs.loadSpoon(). Logs the loaded version.

MacWatcher:start() Method #

Start monitoring system events. Also immediately fires resume hooks and evaluates the current WiFi state.

MacWatcher:stop() Method #

Stop all monitoring, cancel pending timers, fire suspend hooks synchronously, then run any whenStop commands.