@narumitw/pi-caffeinate
v0.13.1
Published
Pi extension that keeps the computer awake while the agent is running.
Maintainers
Readme
☕ 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
/caffeinatecommand 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-statuslinecan add or suppress the status icon from JSON config. - Fails safely when no supported inhibitor is available.
📦 Install
pi install npm:@narumitw/pi-caffeinateTry without installing permanently:
pi -e npm:@narumitw/pi-caffeinateTry 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
/caffeinateOpens keep-awake controls. In non-interactive sessions, it prints command usage and status.
/caffeinate displayKeeps the system and screen/display awake. If an inhibitor is currently active, it is restarted so the new mode applies immediately.
/caffeinate sleepKeeps the system awake while allowing normal display sleep. If an inhibitor is currently active, it is restarted so the new mode applies immediately.
/caffeinate statusShows whether an inhibitor is active, unavailable, disabled, or idle. The status includes the current mode and settings file path.
/caffeinate modeOpens an interactive selector for the keep-awake mode.
/caffeinate stopReleases 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.jsonExample:
{
"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 will be removed in a future major release.
Environment variables
Disable the extension:
PI_CAFFEINATE_DISABLED=1 piUse a custom inhibitor command:
PI_CAFFEINATE_COMMAND='systemd-inhibit --what=idle:sleep --why="pi running" --mode=block sleep infinity' piThe 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 # Pi entrypoint and lifecycle orchestration
│ └── *.ts # Package-local inhibitor and settings modules
├── README.md
├── LICENSE
├── tsconfig.json
└── package.jsonOnly caffeinate.ts is a Pi entrypoint; 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.
