heimdallur 0.1.0

Keep your machine awake while long tasks or agents run.

heimdallur

Keep your machine awake while long tasks or agents run. A thin, dependency-free wrapper around caffeinate (macOS) and systemd-inhibit (Linux), exposed as both a Python library and a CLI.

Install

pip install heimdallur

Library

from heimdallur import StayAwake

with StayAwake(display=False, lid=False):
    run_long_task()

# or explicit control
guard = StayAwake()
guard.start()
try:
    run_long_task()
finally:
    guard.stop()

The guard rolls back automatically on __exit__, stop(), and via an atexit hook even if the process crashes.

CLI

heimdallur                 # stay awake until Ctrl+C
heimdallur -- make build   # stay awake while the command runs
heimdallur -w 12345        # stay awake while PID 12345 is alive

Flags:

• -d, --display — also keep the display awake.
• --lid — prevent sleep even with the lid closed.

⚠️ Warning about --lid

On macOS --lid runs sudo pmset -a disablesleep 1, which means the system will never sleep until it is rolled back to 0. heimdallur rolls this back automatically on exit, but:

• It requires sudo, which may hang on a password prompt in non-interactive (agent) contexts — avoid it there.
• If the process is killed with SIGKILL, rollback cannot run. Re-run sudo pmset -a disablesleep 0 manually if needed.

License

MIT