pi-sleep-guard

English | 中文

Keeps the machine awake while pi agents are running — releases the moment every turn settles.

How it works

Install globally (~/.pi/agent/extensions or as a pi package) and every pi process — your main session and each pi --mode rpc sub-agent child — runs its own guard. Each process holds a platform sleep inhibitor exactly while its own agent is running:

Platform	Holder
macOS	caffeinate -i -w <pid> (-d with PI_SLEEP_GUARD_DISPLAY=1)
Linux	systemd-inhibit --what=sleep:idle (no display axis on this platform)
Windows	PowerShell + SetThreadExecutionState (ES_DISPLAY_REQUIRED optional)

Sleep inhibitors are OR-semantics at the OS level: any single holder keeps the machine awake, so main agent and sub-agents need no coordination whatsoever. Every holder watches its parent pid and self-terminates if the pi process dies — a crash can never leave an orphan blocking sleep.

Guarantees

• Main agent: held from agent_start to agent_settled (covers tool execution and queued continuations between turns).
• Sub-agents that are pi --mode rpc processes (including @everyx/pi-subagent, foreground, background, persistent): each child holds its own lock while running.
• Other background-agent implementations: not promised. If they run as pi RPC children they are covered for free; otherwise only main-agent protection applies.

Honest limits

• User-initiated sleep (lid close, power button, sleep menu) overrides any inhibitor on all three platforms — by OS design.
• On systems without the platform backend (e.g. Linux without systemd), you get a one-time warning; agents keep working, sleep simply isn't blocked.

Config

• PI_SLEEP_GUARD_DISPLAY=1 — also block display off (default: system sleep only, the screen may blank normally).