Metadata-Version: 2.4
Name: heimdallur
Version: 0.2.1
Summary: Keep your machine awake while long tasks or agents run.
Project-URL: Homepage, https://github.com/heimdallur/heimdallur
Project-URL: Repository, https://github.com/heimdallur/heimdallur
Author: maksimpechenin
License: MIT
License-File: LICENSE
Keywords: agent,caffeinate,inhibit,sleep,stay-awake,systemd-inhibit
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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

```bash
pip install heimdallur
```

## Library

```python
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

```bash
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:

```bash
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:

```bash
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
