hs.power
ModuleMonitor and control system power: prevent sleep, read battery state, respond to power events, and lock or sleep the machine.
Preventing sleep
// Prevent the display from sleeping while a task runs
hs.power.preventSleep("display")
// ... do work ...
hs.power.allowSleep("display")
Watching for system events
hs.power.addEventWatcher(event => {
if (event === "screensDidLock") console.log("Screen locked!")
})
Reading battery state
const info = hs.power.batteryInfo()
if (info) {
console.log(`Battery: ${info.percentage}%, ${info.timeRemaining} minutes remaining`)
}
Properties
hs.power.percentage
number
The current battery charge percentage (0–100), or `-1` if no battery is present.
hs.power.isCharging
boolean
Whether the battery is currently charging.
Returns `false` when no battery is present.
hs.power.powerSource
string
The current power source.
Returns `"ac"` when plugged in, `"battery"` when on battery power, `"ups"` when
powered by a UPS, or `"unknown"` if the source cannot be determined.
hs.power.thermalState
string
The current thermal state of the system.
Returns one of: `"nominal"`, `"fair"`, `"serious"`, `"critical"`.
Methods
hs.power.preventSleep(type) -> boolean
Prevents the specified type of system sleep.
Creates an IOKit power assertion that stops macOS from allowing the specified
type of sleep. Call `allowSleep` with the same type to release the assertion.
idle sleep), `"systemIdle"` (prevent system idle sleep), `"system"` (prevent
all system sleep, including from power button or lid close).
Declaration
hs.power.preventSleep(type) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| type | string | The sleep type to prevent. One of: `"display"` (prevent display |
Returns
boolean
`true` if the assertion was created successfully.
Example
hs.power.preventSleep("display")hs.power.allowSleep(type) -> boolean
Releases a previously created sleep prevention assertion.
Declaration
hs.power.allowSleep(type) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| type | string | The sleep type to allow again. One of: `"display"`, `"systemIdle"`, `"system"`. |
Returns
boolean
`true` if an assertion existed and was released, `false` if none was active.
Example
hs.power.allowSleep("display")hs.power.isSleepPrevented(type) -> boolean
Returns whether Hammerspoon is currently preventing the specified type of sleep.
Declaration
hs.power.isSleepPrevented(type) -> booleanParameters
| Name | Type | Description |
|---|---|---|
| type | string | The sleep type to check. One of: `"display"`, `"systemIdle"`, `"system"`. |
Returns
boolean
`true` if this sleep type is currently being prevented.
Example
if (hs.power.isSleepPrevented("display")) console.log("display sleep is prevented")hs.power.declareActivity() -> None
Simulates user activity, briefly resetting the display idle timer.
Equivalent to moving the mouse — does not create a persistent assertion.
Declaration
hs.power.declareActivity() -> NoneReturns
None
Example
hs.power.declareActivity()hs.power.currentAssertions() -> NSArray
Returns the active power management assertions from all processes on the system.
Declaration
hs.power.currentAssertions() -> NSArrayReturns
NSArray
An array of objects with `pid` (number), `name` (string), and `type` (string) properties.
Example
hs.power.currentAssertions().forEach(a => console.log(a.pid + " " + a.name))hs.power.systemSleep() -> None
Puts the system to sleep immediately.
Requires the Automation permission for System Events.
Declaration
hs.power.systemSleep() -> NoneReturns
None
Example
hs.power.systemSleep()hs.power.lockScreen() -> None
Locks the screen immediately.
Declaration
hs.power.lockScreen() -> NoneReturns
None
Example
hs.power.lockScreen()hs.power.startScreensaver() -> None
Starts the screensaver immediately.
Declaration
hs.power.startScreensaver() -> NoneReturns
None
Example
hs.power.startScreensaver()hs.power.batteryInfo() -> NSDictionary
Returns a snapshot of all available battery information, or `null` if no battery is present.
Declaration
hs.power.batteryInfo() -> NSDictionaryReturns
NSDictionary
An object with battery fields, or `null` if no battery is present.
Example
const info = hs.power.batteryInfo()
if (info) console.log(`${info.percentage}% — ${info.timeRemaining}m remaining`)hs.power.addEventWatcher(listener) -> None
Registers a listener that fires when system power events occur.
`"screensDidSleep"`, `"screensDidWake"`, `"screensDidLock"`, `"screensDidUnlock"`,
`"screensaverDidStart"`, `"screensaverDidStop"`, `"screensaverWillStop"`,
`"systemWillSleep"`, `"systemDidWake"`, `"systemWillPowerOff"`,
`"sessionDidBecomeActive"`, `"sessionDidResignActive"`.
The OS notification subscription starts lazily on the first listener and
is released automatically when the last listener is removed.
Declaration
hs.power.addEventWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | JSValue | A function receiving `(eventName: string)`. |
Returns
None
Example
hs.power.addEventWatcher(event => console.log("Power event: " + event))hs.power.removeEventWatcher(listener) -> None
Removes a previously registered power event listener.
Declaration
hs.power.removeEventWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | JSValue | The function originally passed to `addEventWatcher`. |
Returns
None
Example
const handler = event => console.log(event)
hs.power.addEventWatcher(handler)
hs.power.removeEventWatcher(handler)hs.power.addBatteryWatcher(listener) -> None
Registers a listener that fires whenever battery state changes.
The listener receives no arguments; call `batteryInfo()` or read individual
properties inside the callback to determine what changed.
The OS notification subscription starts lazily on the first listener and
is released automatically when the last listener is removed.
Declaration
hs.power.addBatteryWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | JSValue | A function called with no arguments on battery state change. |
Returns
None
Example
hs.power.addBatteryWatcher(() => {
console.log("Battery now: " + hs.power.percentage + "%")
})hs.power.removeBatteryWatcher(listener) -> None
Removes a previously registered battery change listener.
Declaration
hs.power.removeBatteryWatcher(listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| listener | JSValue | The function originally passed to `addBatteryWatcher`. |
Returns
None
Example
const handler = () => console.log("battery changed")
hs.power.addBatteryWatcher(handler)
hs.power.removeBatteryWatcher(handler)