Mac Keepawake

Mac Keepawake

Mental Model

Screen lock is fine. System sleep is the problem: it pauses local processes, network I/O, and Terminal jobs. Keep the Mac awake while the screen still locks or turns off, prevent idle system sleep, and leave the security lock on unless the user explicitly asks otherwise. The process target is Terminal work such as Claude Code, Codex, dev servers, or long-running shell jobs.

Workflow

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

2. Choose the mode from the request before changing setup. For persistent keepawake, use the bundled scripts/mac_keepawake.py beside this SKILL.md. For one command or a bounded session, use the temporary mode below. Resolve the skill directory first:

SKILL_DIR=~/.codex/skills/mac-keepawake   # or the mac-keepawake/ directory of a clone
python3 "$SKILL_DIR/scripts/mac_keepawake.py" install
python3 "$SKILL_DIR/scripts/mac_keepawake.py" status

3. 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
• Logs: ~/Library/Logs/mac-keepawake.log and ~/Library/Logs/mac-keepawake.err

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

Validation

For persistent setup, claim success only when these checks are true:

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

For temporary mode, verify the launched caffeinate process and its applicable assertions; no LaunchAgent is required. When a persistent check fails, read the log files above, then re-run status.

Safety Notes

• Leave lock-screen, password, FileVault, firewall, and remote-login settings exactly as they are; this task changes only the LaunchAgent and its caffeinate process.
• Leave other caffeinate and Amphetamine processes running; act only on the com.codex.mac-keepawake label and its plist.
• Removal goes through the script's uninstall command, which targets that same 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.