Mac keepawake

Mac Keepawake

Outcome

Keep the Mac awake while allowing the screen to lock or turn off. The process target is Terminal work such as Claude Code, Codex, dev servers, or long-running shell jobs.

Mental Model

Screen lock is fine. System sleep is the problem: it pauses local processes, network I/O, and Terminal jobs. Prevent idle system sleep; do not disable security lock unless the user explicitly asks.

Workflow

1. Restate the goal: keep processes running after lock, not bypass lock.
2. Inspect current state before changing anything:

pmset -g custom
pmset -g assertions
launchctl print "gui/$(id -u)/com.codex.mac-keepawake" 2>/dev/null || true

3. Prefer the bundled script for persistent setup:

python3 path/to/mac-keepawake/scripts/mac_keepawake.py install
python3 path/to/mac-keepawake/scripts/mac_keepawake.py status

4. Report exact evidence from launchctl print and pmset -g assertions.

Choosing a Mode

• Persistent login session: install the LaunchAgent. This survives new Terminal windows and restarts at login.
• Temporary command session: run caffeinate -i -s <command> when the user wants only one command protected.
• Battery-sensitive work: warn that -s only asserts full system sleep prevention on AC power; battery behavior may depend on macOS power policy.

Persistent Setup

The script creates this user LaunchAgent:

• Label: com.codex.mac-keepawake
• Plist: ~/Library/LaunchAgents/com.codex.mac-keepawake.plist
• Command: /usr/bin/caffeinate -i -s

Use install to write and bootstrap the agent, status to inspect assertions, and uninstall only when the user asks to remove it.

Validation

Claim success only when these checks are true:

• launchctl print gui/$(id -u)/com.codex.mac-keepawake shows state = running or job state = running.
• pmset -g assertions lists caffeinate with PreventUserIdleSystemSleep.
• If on AC power, pmset -g assertions should also list PreventSystemSleep.

Safety Notes

• Do not change lock-screen, password, FileVault, firewall, or remote-login settings for this task.
• Do not kill unrelated caffeinate or Amphetamine processes.
• Do not use destructive cleanup commands. The only removal path should be the script's own uninstall command for the matching label and plist.
• Explain that logout, reboot, shutdown, or a kernel panic will still stop ordinary Terminal processes. Recommend tmux or screen for session reattachment when relevant.