stay-awake

Stay Awake

Overview

Keep macOS awake during agent work using caffeinate with a bounded lifecycle. Prefer process-coupled assertions, then timeout-based assertions, and only use unbounded assertions with explicit cleanup.

GitHub Copilot CLI runs through shell-backed sessions and tool execution. In practice, the most reliable wake assertion target is the shell or concrete command process that will own the long-running work, not an abstract "agent" process. If the work is started from a shell, capture that shell's PID with $$; if it is started from a wrapper script or a specific child process, use that process ID instead.

When to Use

Use this skill when:

• The session may run long enough for idle sleep to interrupt work
• You are running long tests, builds, or debugging loops on macOS
• You need predictable wake-lock cleanup at session end

Do not use this skill on non-macOS systems.

Decision Order

1. Attach to the agent process when possible (best)
2. Use a timeout when process attachment is not possible
3. Use bare caffeinate only as fallback, then always cancel at session end

Quick Reference

Situation	Command	Cleanup behavior
Agent process ID is known	caffeinate -i -w <process_id>	Stops automatically when process exits
Duration is known	caffeinate -i -t <seconds>	Stops automatically at timeout
No PID and no duration	caffeinate -i	Must be manually stopped
Long single command	caffeinate -i <command> [args...]	Stops when wrapped command exits

Workflow

1) Prefer a process-coupled wake lock

If the shell or long-running command process ID is available, tie the assertion to that process:

caffeinate -i -w <process_id>

If the work is started from a shell, the current shell's process ID can be read directly with $$ and used immediately:

agent_process_id=$$
caffeinate -i -w "$agent_process_id"

This is the safest default because wakefulness ends with the process that owns the long-running work. If the agent is not running inside a shell, if the chosen process exits immediately, or if the work is being driven by a wrapper process instead of a shell, prefer a timeout or a fallback caffeinate -i with cleanup instead.