# Mac Keepawake

> Keep macOS awake during Terminal or agent work while preserving screen lock. Use for a temporary caffeinate session or persistent keepawake LaunchAgent.

- Skill: `cskwork/mac-keepawake` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add cskwork/mac-keepawake`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cskwork/mac-keepawake/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cskwork (https://skillmd.com/u/cskwork)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cskwork/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:

```bash
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:

```bash
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.