How to use the Anti-Sleep Mac keep-awake agent skill

What an agent skill is and what anti-sleep does

An agent skill is a folder with a SKILL.md file that gives an AI agent specific instructions for one task. When the skill is installed and relevant to your request, the agent follows its guidance.

The anti-sleep skill covers one job: keeping a Mac awake during a long supervised task. It uses caffeinate, a command that already ships with macOS, so no extra software is needed. The agent picks sensible flags, sets a time limit, and checks that the sleep block is active.

• Prevents idle system sleep for a set duration, for example during a two-hour build.
• Can keep the display on when the task needs a visible screen.
• Can tie the block to a running process so it ends when that process exits.
• Explains that the block ends silently when its timer runs out.

Install the anti-sleep skill

Download the ZIP for the skill from this page. Unzip it into one of two places, depending on how you want to use it.

For personal use across projects, unzip it into ~/.claude/skills/. To limit it to a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead of files on disk, upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Single project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. Describe the task and say that the Mac should stay awake. The skill is meant for requests where a long task should not be interrupted by sleep, so mention the job and roughly how long it will take.

If you want the agent to keep a build from being interrupted, say so directly. The agent should then start caffeinate and confirm the process ID, the flags and the time it will expire.

• "Keep my Mac awake while the test suite runs, about three hours."
• "Stop the Mac sleeping during this large download."
• "I'm watching this automation run overnight. Keep the machine awake until it finishes."
• "Is the Mac still being kept awake? Check before I leave."

Choose the right flags and time limit

The default is -i with -t set in seconds. The -i flag stops idle system sleep but the screen may still dim or lock. Add -d only when the task needs the display on.

Duration is set with -t and seconds. Two hours is 7200, seven hours is 25200, and nine hours is 32400.

To keep the block tied to a job instead of a timer, use -w with a process ID, or wrap a command so caffeinate exits when it finishes.

• -i: prevent idle system sleep only
• -d: prevent display sleep
• -d -i: screen on and system awake
• -d -i -s: also prevent system sleep while on AC power (only when plugged in)
• -u -t 1: wake the display now
• -w <PID>: stay awake until that process exits

Verify the block and stop it early

caffeinate prints nothing and holds the prompt, so it can look stuck. It is not stuck. Check whether it is running with pgrep rather than looking at the terminal. The pmset assertions output shows whether sleep prevention is active.

If you asked for a timed block and come back after hours, check pgrep first. The block may have expired silently.

To stop early, the skill says to stop the PID it recorded for this task, or press Ctrl+C in the pane running it. It warns against stopping unrelated caffeinate sessions with a broad pattern.

• Check it is running: pgrep -fl caffeinate
• Check elapsed time: ps -o etime= -p <PID>
• Check sleep assertions: pmset -g assertions

Run it in a visible terminal pane (optional)

The skill prefers running caffeinate in your own terminal pane so it is visible and easy to stop with Ctrl+C. This uses the cmux terminal, and the skill says to read the cmux skill first when working with panes. Otherwise the agent runs it as a background task and does not block its own foreground shell.

Know the limits

These assertions do not keep work going through lid closure, shutdown or loss of power, and they do not replace your lock-screen policy. The keyboard backlight is a separate case: caffeinate cannot keep it on, so you must change the setting manually in System Settings > Keyboard > "Turn keyboard backlight off after inactivity" > Never.

The skill also says that long or unattended runs need explicit approval, and that commands and file-changing workflows should be confirmed against the target environment first.

• Lid closure, shutdown and power loss are not covered.
• Keyboard backlight needs a one-time manual setting change.
• Long runs need explicit user approval.