☕ 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, unless quiet mode is enabled.
• 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 and optional quiet 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 standard keep-awake controls in TUI or RPC mode. Print and JSON modes reject the interactive menu observably; use the direct status, sleep, display, stop, or help routes instead.

/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, quiet mode, and settings file path.

/caffeinate mode

Opens the standard keep-awake mode selector in TUI or RPC mode. Escape closes the selector.

/caffeinate stop

Releases any active inhibitor until Pi starts another agent run.

⚙️ Configuration

Persisted settings

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

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

Example:

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

Set "quiet": true to hide the routine Keeping computer awake (...) and Released pi-caffeinate (agent finished) lifecycle notifications and keep the caffeinate status item clear while active or unavailable. Quiet mode does not hide warnings or explicit feedback from /caffeinate commands such as status, mode changes, help, and manual stop. It defaults to false when omitted. The file is read at startup and on /reload; run /reload after editing it in a running Pi session before using mode commands.

Missing, invalid, or deleted settings default back to display mode with quiet mode disabled on every supported OS. A missing file stays absent until the first successful mode change. Within one Pi process, mode saves run in invocation order, reread the latest valid document, and preserve unknown fields. Malformed JSON or an invalid recognized field blocks mode saves until repaired instead of being overwritten. A failed save keeps the prior runtime mode; if restarting an active inhibitor fails after publication, the extension restores the prior saved mode and inhibitor behavior or reports an explicit rollback failure.

Compatibility: older versions used pi-caffeinate-settings.json. A legacy-only file remains readable with a warning and is never modified automatically; rename it to pi-caffeinate.json. The first subsequent settings save writes the canonical file. If both files exist, pi-caffeinate.json wins and the legacy file is ignored. The legacy filename is deprecated and will be removed in a future 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.json:

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

Without @narumitw/pi-statusline, keep using PI_CAFFEINATE_ICON during the compatibility window. In pi-statusline.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/
│   ├── index.ts       # Pi package entrypoint
│   ├── caffeinate.ts  # Extension registration and lifecycle orchestration
│   └── *.ts           # Package-local inhibitor and settings modules
├── README.md
├── LICENSE
├── tsconfig.json
└── package.json

index.ts is the Pi entrypoint and forwards to caffeinate.ts; the other source modules are internal.

🔎 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.