heimdallur 0.2.1

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.

Auto-mode (Cursor Hooks)

Install once and heimdallur will start automatically at the beginning of every Cursor agent session — no skill trigger needed:

pip install heimdallur
heimdallur --install-hooks

This writes a sessionStart hook entry into ~/.cursor/hooks.json (merging into any existing config without touching other hooks) and places the companion script at ~/.cursor/hooks/heimdallur-session.sh.

To remove the hooks:

heimdallur --uninstall-hooks

Note: --install-hooks modifies ~/.cursor/hooks.json at the user level (not project level). If Cursor is not installed, the command will exit with an error.

⚠️ 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