Skip to content

About

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

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

MacWatcher Spoon

MIT License Hammerspoon Spoon Documentation

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/.

About

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

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages