☕ pi-caffeinate — Keep Your Computer Awake While Pi Works

@narumitw/pi-caffeinate is a cross-platform Pi coding agent extension that prevents your computer from sleeping while the Pi agent is processing a prompt.

It is designed for long-running coding, refactoring, debugging, web research, and autonomous agent workflows where a suspended laptop or desktop would interrupt progress.

✨ Features

• Starts an OS sleep inhibitor when Pi begins processing (agent_start).
• Releases the inhibitor when processing ends (agent_end) or the session shuts down.
• Publishes the active keep-awake mode as status while an inhibitor is active.
• Supports macOS, Windows, WSL, and Linux.
• Defaults to display-awake mode on every supported OS: prevent system sleep and keep the screen/display awake.
• Provides a single /caffeinate command with menu-based controls and direct subcommands.
• Persists the selected keep-awake mode in a small JSON settings file.
• Allows a custom inhibitor command through environment configuration.
• Emits plain status text; @narumitw/pi-statusline can add or suppress the status icon from JSON config.
• Fails safely when no supported inhibitor is available.

📦 Install

pi install npm:@narumitw/pi-caffeinate

Try without installing permanently:

pi -e npm:@narumitw/pi-caffeinate

Try this package locally from the repository root:

pi -e ./extensions/pi-caffeinate

🖥️ Supported platforms

The default mode is display on every supported OS. That means pi-caffeinate prevents system sleep, suspend, or hibernate and keeps the screen/display awake.

Use /caffeinate sleep if you want to prevent system sleep while allowing normal display idle behavior such as screen blanking or monitor power-off.

| Platform | sleep mode | display mode, default | | --- | --- | --- | | macOS | caffeinate -ims | caffeinate -dimsu | | Windows | PowerShell SetThreadExecutionState(0x80000001) | PowerShell SetThreadExecutionState(0x80000003) | | WSL | Windows powershell.exe with SetThreadExecutionState(0x80000001) | Windows powershell.exe with SetThreadExecutionState(0x80000003) | | Linux with systemd | systemd-inhibit --what=sleep ... sleep infinity | systemd-inhibit --what=idle:sleep ... sleep infinity | | Linux fallback | caffeinate -ims when available | caffeinate -dimsu when available |

If no supported inhibitor is available, the extension stays loaded and reports that caffeinate is unavailable.

🚀 Commands

/caffeinate

Opens keep-awake controls. In non-interactive sessions, it prints command usage and status.

/caffeinate display

Keeps the system and screen/display awake. If an inhibitor is currently active, it is restarted so the new mode applies immediately.

/caffeinate sleep

Keeps the system awake while allowing normal display sleep. If an inhibitor is currently active, it is restarted so the new mode applies immediately.

/caffeinate status

Shows whether an inhibitor is active, unavailable, disabled, or idle. The status includes the current mode and settings file path.

/caffeinate mode

Opens an interactive selector for the keep-awake mode.

/caffeinate stop

Releases any active inhibitor until Pi starts another agent run.

⚙️ Configuration

Persisted mode

/caffeinate sleep and /caffeinate display save the selected mode to:

${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-caffeinate.json

Example:

{
  "mode": "display",
  "updatedAt": 1791763200000
}

Missing, invalid, or deleted settings default back to display mode on every supported OS.

Compatibility: older versions used pi-caffeinate-settings.json. During the migration window, a legacy-only file is automatically migrated to pi-caffeinate.json with a warning. If both files exist, pi-caffeinate.json wins and the legacy file is ignored. The legacy filename is deprecated and planned for removal after at least one minor release cycle, preferably 4–8 weeks, or at the next major release.

Environment variables

Disable the extension:

PI_CAFFEINATE_DISABLED=1 pi

Use a custom inhibitor command:

PI_CAFFEINATE_COMMAND='systemd-inhibit --what=idle:sleep --why="pi running" --mode=block sleep infinity' pi

The custom command is parsed with shell-like quoting and is run directly without a shell. PI_CAFFEINATE_COMMAND takes precedence over the saved mode; /caffeinate status reports when a custom command is active.

Deprecated: PI_CAFFEINATE_ICON still works for now. If you use @narumitw/pi-statusline, move the icon to ${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-statusline-settings.json:

{
  "extensionStatusIcons": {
    "caffeinate": "☕️"
  }
}

Without @narumitw/pi-statusline, keep using PI_CAFFEINATE_ICON during the compatibility window. In pi-statusline-settings.json, use an empty string to show the caffeinate status without an icon.

🧠 Why use pi-caffeinate?

AI coding agents often run tool-heavy tasks that take several minutes. pi-caffeinate keeps your machine awake during active Pi work, helping browser automation, local builds, test runs, code generation, and long prompts finish reliably.

The default display-awake mode prioritizes uninterrupted long-running Pi work across platforms, including Linux desktops that require idle inhibition to prevent automatic suspend. Use /caffeinate sleep (shown as system-awake in status output) when you prefer normal screen power saving and your system does not need idle inhibition to keep Pi running.

🗂️ Package layout

extensions/pi-caffeinate/
├── src/
│   └── caffeinate.ts
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

🔎 Keywords

Pi extension, Pi coding agent, caffeinate, prevent sleep, keep awake, sleep inhibitor, AI agent automation, long-running coding task, TypeScript Pi package.

📄 License

MIT. See LICENSE.