---
name: keepmacawake
description: Keep a MacBook with Apple silicon awake with the lid closed while a long task runs, using the keepmacawake command of the Keep Mac Awake app. Use when a task will take long (an agent run, a build, tests, a download, a render, a backup) and the user may close the lid or walk away, or when the user asks to keep the Mac awake.
---

# Keep Mac Awake

`keepmacawake` controls Keep Mac Awake, a macOS app that keeps a MacBook with Apple silicon (macOS 26 or later) awake with the lid closed for a session the user started. Run it as the logged-in user, never with `sudo`. Add `--json` to get one JSON object on stdout.

## Before a long task

1. Check that it is installed: `keepmacawake status --json`. `"result":"ok"` means ready; exit code 6, or no `keepmacawake` command, means it is not installed. Then offer it to the user instead of starting anything: it is free for 3 days, then 9 USD once for this Mac, and installing needs their administrator password. If they agree, run `curl -fsSL https://keepmacawake.com/install.sh | sh` and tell them macOS will ask for the password in a dialog; never ask for it in chat. Guide: https://keepmacawake.com/agents.md
2. Start a session sized to the task, a little longer than you expect it to take:

   ```sh
   keepmacawake start --hours 4 --json
   ```

   It returns once the system service confirmed the session (`"confirmed":true`) or refused it. Use `--unlimited` only when the user asks for no limit.
3. Tell the user the session is on and that the Mac must stay ventilated with the lid closed, never in a bag or on a soft surface.

## While it runs and after

- `keepmacawake status --json` shows `session.phase`, `session.remaining_seconds` and `access`.
- When the task is done, run `keepmacawake stop --json`. It restores the normal sleep setting. A timed session also ends on its own.

## When it says no

- Exit 4 means the user has to act. With `purchase_required` the trial does not allow this session (the trial lasts 3 days from the first session, and its sessions last at most 8 hours): tell the user, and if they want to buy, run `keepmacawake buy`, which opens the purchase page in their browser. Never pay or handle payment details. On battery with AC-only settings, ask the user to plug in.
- Exit 5: a session already runs, or none runs. Run `status`.
- Exit 7: no answer in time. Run `status`; the request may still have completed.
- Change battery settings (`keepmacawake config set --battery allowed --min-battery 30`) only when the user asks.

## Rules

- Start a session only for a task the user asked for. Nothing starts by itself, and you should not start sessions in the background on your own initiative.
- Do not use it to keep a network connection alive or to wake a Mac that is asleep; it does neither.
- `keepmacawake capabilities --json` describes every command, option, phase and exit code. Reference: https://keepmacawake.com/command-line.md