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.on("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() -> [[String: Any]]
Returns the active power management assertions from all processes on the system.
Declaration
hs.power.currentAssertions() -> [[String: Any]]Returns
[[String: Any]]
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
Notes
This function uses private API to lock the screen, it may break in a future macOS update
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() -> [String: Any]
Returns a snapshot of all available battery information, or `null` if no battery is present.
Declaration
hs.power.batteryInfo() -> [String: Any]Returns
[String: Any]
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.on(event, listener) -> None
Register a listener for system power/session events, or battery state changes.
Declaration
hs.power.on(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for. `"change"` fires whenever battery state changes; the rest are system power/session events. |
| listener | any | Called with no arguments when the event occurs; call batteryInfo() inside a "change" listener to inspect the new battery state |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.power.on('systemWillSleep', () => console.log("Going to sleep"))
hs.power.on('change', () => console.log("Battery now: " + hs.power.batteryInfo().percentage + "%"))
} catch (err) {
console.error(err.message)
}hs.power.off(event, listener) -> None
Remove a previously registered hs.power listener.
Declaration
hs.power.off(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event the listener was registered for |
| listener | any | The function originally passed to `on` |
Returns
None
Example
const onSleep = () => console.log("sleeping")
hs.power.on('systemWillSleep', onSleep)
// later…
hs.power.off('systemWillSleep', onSleep)hs.power.once(event, listener) -> None
Register a listener that fires at most once for the given hs.power event.
Declaration
hs.power.once(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for |
| listener | any | Called once, then automatically removed |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.power.once('systemDidWake', () => console.log("Welcome back"))
} catch (err) {
console.error(err.message)
}