Mac Keepawake Codex Skill

Codex skill for keeping macOS awake while Claude Code, Codex, dev servers, or long-running Terminal jobs continue running after the screen is locked.

What It Does

This skill guides an agent through the safe macOS path for locked-screen work:

• Inspect current pmset, launchctl, and sleep assertion state.
• Install a user LaunchAgent that runs /usr/bin/caffeinate -i -s.
• Verify that caffeinate is actively preventing idle system sleep.
• Keep screen lock and security settings untouched.

The key distinction: screen lock is not the problem; system sleep is. This skill prevents idle sleep while still allowing the Mac to lock.

Install

Clone this repository, then copy or symlink the skill folder into your Codex skills directory:

git clone https://github.com/cskwork/mac-keepawake-codex-skill.git
cd mac-keepawake-codex-skill
mkdir -p ~/.codex/skills
ln -s "$PWD/mac-keepawake" ~/.codex/skills/mac-keepawake

Restart Codex or start a fresh session so the skill metadata is loaded.

Use

Invoke the skill explicitly:

Use $mac-keepawake to keep my Mac awake while Terminal agents continue running.

The bundled script can also be run directly:

python3 mac-keepawake/scripts/mac_keepawake.py install
python3 mac-keepawake/scripts/mac_keepawake.py status
python3 mac-keepawake/scripts/mac_keepawake.py uninstall

Behavior

The persistent setup creates:

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

Validation should show caffeinate in pmset -g assertions with PreventUserIdleSystemSleep. On AC power, it should also show PreventSystemSleep.

Limits

This does not preserve Terminal processes across logout, reboot, shutdown, or crashes. Use tmux or screen when you also need reattachable sessions.

License

MIT