ControlPlane.spoon
A Hammerspoon Spoon that switches named "contexts" based on
weighted evidence from wifi, USB, displays, power source, and IP subnet. A
lightweight reimplementation of the (defunct) macOS app ControlPlane.
Install
hs.loadSpoon("ControlPlane")
Drop this directory into ~/.hammerspoon/Spoons/ (or install via your
preferred Spoon workflow).
Usage
hs.loadSpoon("ControlPlane")
spoon.ControlPlane.threshold = 1.0 -- min score to leave "none"
spoon.ControlPlane.margin = 0.3 -- top − next gap required to switch
spoon.ControlPlane.debug = 2 -- 0 silent · 1 events · 2 +detection · 3 +evidence
spoon.ControlPlane.contexts = {
work = {
rules = {
{ kind = "ssid", confidence = 0.5, value = {"work-wifi"} },
{ kind = "bssid", confidence = 0.5, value = {"aa:bb:cc:dd:ee:ff"} },
},
actions = { -- opaque to the Spoon, passed to onContextChange
displaySleepOnBattery = 5,
displaySleepOnCharger = 10,
},
},
home = {
rules = {
{ kind = "ssid", confidence = 0.5, value = {"home-wifi"} },
{ kind = "screen", confidence = 0.7, value = {"07B960D6-7DC5-42B8-BD66-..."} },
{ kind = "usb", confidence = 0.5, value = {{vendorID = 1507, productID = 1865}} },
{ kind = "power", confidence = 0.2, value = {"AC Power"} },
{ kind = "subnet", confidence = 0.6, value = {"192.168.13.0/24"} },
},
actions = { displaySleepOnBattery = 5, displaySleepOnCharger = 20 },
},
none = { rules = {}, actions = { displaySleepOnBattery = 2, displaySleepOnCharger = 5 } },
}
spoon.ControlPlane.onContextChange = function(name, ctx, oldName)
-- react to the switch; ctx.actions is your own opaque payload
end
spoon.ControlPlane:start()
Concepts
- Context — a named
{ rules = {...}, actions = {...} } bundle. actions
is opaque to the Spoon; do what you like with it in onContextChange.
- Rule —
{ kind, confidence, value }. value is always list-shaped; a
rule matches if any listed entry matches the evidence.
- Evidence — a snapshot gathered from
hs.wifi.interfaceDetails,
hs.usb.attachedDevices, hs.screen.allScreens, hs.battery.powerSource,
and hs.network.addresses.
Rule kinds
| kind |
value shape |
matches when |
ssid |
{"name", ...} |
current SSID equals any listed name |
bssid |
{"aa:bb:cc:dd:ee:ff", ...} |
current BSSID equals any listed value |
usb |
{{vendorID=N, productID=M}, ...} |
any attached device matches |
screen |
{"UUID", ...} |
any attached screen UUID matches |
power |
{"AC Power"} / {"Battery Power"} |
current power source matches |
subnet |
{"192.168.0.0/24", ...} |
any local IPv4 falls in a listed CIDR |
Selection algorithm
- Gather evidence from all sources.
- Score each non-
none context by summing confidences of matching rules.
- If top score <
threshold, select "none".
- If (top − runner-up) ≥
margin, switch to the top context (clear winner).
- Otherwise evidence is ambiguous — stay in the current context (sticky).
Prevents flapping as peripherals come and go.
All detection is event-driven via hs.wifi, hs.usb, hs.screen, and
hs.battery watchers. No polling. The battery watcher is debounced to fire
only on actual power-source transitions.
Populating rule values
Run in the Hammerspoon console:
hs.inspect(hs.wifi.interfaceDetails()) -- ssid, bssid
for _,s in ipairs(hs.screen.allScreens()) do print(s:name(), s:getUUID()) end -- screen UUID
hs.inspect(hs.usb.attachedDevices()) -- usb VID/PID
hs.battery.powerSource() -- "AC Power" / "Battery Power"
hs.inspect(hs.network.addresses()) -- ip addresses
Grant Location Services to Hammerspoon — hs.wifi.interfaceDetails() returns
SSID/BSSID only when granted. Trigger the prompt once with hs.location.start().
Screen UUIDs are derived from EDID: generally unique per physical unit, but
not guaranteed on budget panels with missing or duplicated serials.
API
| Symbol |
Description |
spoon.ControlPlane.contexts |
Table of {name = {rules, actions}} |
spoon.ControlPlane.threshold |
Minimum score to leave "none" (default 1.0) |
spoon.ControlPlane.margin |
Required top − next gap to switch (default 0.3) |
spoon.ControlPlane.debug |
0..3 verbosity (default 0) |
spoon.ControlPlane.onContextChange |
function(newName, newCtx, oldName) callback |
spoon.ControlPlane:start() |
Register watchers and run an initial detection |
spoon.ControlPlane:stop() |
Tear down all watchers |
spoon.ControlPlane:reevaluate() |
Force a re-detection |
spoon.ControlPlane:currentContext() |
Name of the currently-applied context |
Extending
To add a new rule kind:
- Gather the raw signal in
_gatherEvidence().
- Add a branch in
ruleMatches().
- Keep
value list-shaped.
- If the signal has its own event source, register a watcher in
:start()
and tear it down in :stop().
License
MIT — see LICENSE.md.
© 2026 Luca Filipozzi. Some rights reserved. See LICENSE.