A Pi extension that prevents macOS from entering idle system sleep while the agent is working.
It keeps the machine awake during model responses, tool calls, retries, compaction retries, queued continuations, and tools waiting for user input. The sleep assertion is released as soon as the agent fully settles.
This extension has been checked and verified on macOS. It requires:
- Pi (
@earendil-works/pi-coding-agent) - The
caffeinatecommand available onPATH
caffeinate is supplied by macOS and is not bundled with this extension. Its location does not matter as long as the command is accessible. Verify it before installation:
command -v caffeinateThe repository also includes a dependency check:
node scripts/check-caffeinate.mjsGit-based Pi installations run this check through the package installation hook. Because local policies can disable installation hooks, the extension checks again at runtime. If the command is unavailable, the extension disables itself and displays a warning instead of attempting to start a missing command.
Install directly from this Git repository:
pi install git:github.com/forlorn-echo/pi-caffeinateInstall a tagged release for a reproducible version:
pi install git:github.com/forlorn-echo/pi-caffeinate@v1.0.0Add -l for a project-local installation:
pi install git:github.com/forlorn-echo/pi-caffeinate -lStart or restart Pi after installation. Use pi list to inspect installed packages and pi config to enable or disable the extension.
Load the extension from a clone of this repository:
pi -e ./pi-caffeinate.tsOr load the Git package temporarily for one run:
pi -e git:github.com/forlorn-echo/pi-caffeinateWhile the agent is active, the extension runs:
caffeinate -i -t 300The -i flag prevents idle system sleep. Each assertion expires after five minutes as a fail-safe and is refreshed every four minutes while work continues. This ensures that a force-killed Pi process cannot leave a permanent sleep assertion behind.
The assertion is stopped on both agent_settled and session_shutdown.