domains / devops / macos-caffeinate-anti-sleep / anti-sleep

anti-sleep

Skill card

combined

The two copies implement the same goal but with materially different, non-interchangeable procedures. The davidondrej copy mandates a bundled LaunchAgent-based launcher (scripts/anti-sleep.sh) with strict rules against raw backgrounding, automatic replacement of active sessions, and a separate verify step. The sickn33 copy is a direct-caffeinate approach that explicitly recommends running in a visible cmux pane or as a background task, uses pgrep/pmset for verification, and includes a 'gotcha' about the silent prompt. Crowning one would hide a real alternative (managed LaunchAgent vs. direct process).

Repositories

Other copies

Combined skill

---
name: anti-sleep
description: Keep a Mac awake for a set duration or while a process runs.
---

# Anti-Sleep (macOS caffeinate)

## Method Selection

1. **Managed Launcher (Preferred if available):** If the `scripts/anti-sleep.sh` launcher is present in the skill directory, use it. It creates a one-shot user LaunchAgent.
   - **Never** launch `caffeinate` with raw `&`, `nohup`, `disown`, or `launchctl submit` when using this method.
   - Resolve `scripts/anti-sleep.sh` relative to this `SKILL.md`.

2. **Direct Caffeinate (Fallback/Alternative):** If the launcher is not available or the user prefers a visible process, use direct `caffeinate` commands.
   - Prefer running in a visible terminal or cmux pane so the user can `Ctrl+C`.
   - If running in the background, ensure it does not block the foreground shell.

## Workflow

### 1. Inspect State
- **Launcher:** Run `scripts/anti-sleep.sh status`.
- **Direct:** Run `pgrep -fl caffeinate` to check for existing sessions.

### 2. Handle Existing Sessions
- **Launcher:** If an active session exists and a new duration is requested, automatically stop the old session (`scripts/anti-sleep.sh stop`). Do not ask for confirmation.
- **Direct:** If an existing session is found, verify the PID and command. If it is the one to be replaced, stop it (`kill <PID>` or `Ctrl+C`). Do not use broad `pkill`.

### 3. Start Anti-Sleep
- **Launcher:**
  - Timer: `scripts/anti-sleep.sh start <seconds> [flags]`
  - Process: `scripts/anti-sleep.sh start-pid <PID> [flags]`
- **Direct:**
  - Timer: `caffeinate -d -i -t <seconds> [flags]`
  - Process: `caffeinate -d -i -w <PID>` or `caffeinate -i <command>`

**Default Flags:** `-d -i` (keep display on and prevent idle system sleep).
- `-i`: Prevent idle system sleep.
- `-d`: Prevent display sleep.
- `-s`: Prevent system sleep on AC power (only works when plugged in).

### 4. Verify
- **Launcher:** In a **separate tool/shell call** after start, run `scripts/anti-sleep.sh verify`. Only report success if `STATUS=running` and `ASSERTIONS=active`.
- **Direct:** Run `pgrep -fl caffeinate` to confirm the process and flags. Run `pmset -g assertions` to confirm `PreventUserIdleSystemSleep` and `PreventUserIdleDisplaySleep` are active.

### 5. Report
- Confirm to the user the PID, flags, and wall-clock expiry time.
- **Gotcha (Direct):** `caffeinate` prints nothing and holds the prompt. It is not stuck. Verify with `pgrep`.

## Stop Early
- **Launcher:** `scripts/anti-sleep.sh stop`
- **Direct:** `kill <PID>` or `Ctrl+C` in the pane.

## Fallback
- If `launchctl bootstrap` fails (Launcher method), use a visible persistent terminal or cmux pane.
- If no persistent surface is available, tell the user instead of starting an unreliable background job.

## Keyboard Backlight
- `caffeinate` cannot keep the keyboard backlight on.
- Manual fix: System Settings → Keyboard → “Turn keyboard backlight off after inactivity” → Never.