Contact
Speranda/Keep Awake/Docs

User Guide

Keep Awake is a tiny, native macOS menu bar app that stops your Mac from sleeping. It is a simple, no-fuss replacement for typing caffeinate in the terminal. It lives in the menu bar, with no Dock icon and no windows in the way. New in version 2.0, it can also keep your Mac awake for your AI coding agents while they work.

Made by Speranda. Tool page: https://speranda.com/tool.html?tool=keep-awake

Contents

Requirements

Requires macOS 13 Ventura or later, Apple silicon.

Install

  1. Download Keep Awake from https://speranda.com/tool.html?tool=keep-awake. You will get a disk image (.dmg).
  2. Open the disk image and drag the Keep Awake cup onto your Applications folder.
  3. Open Keep Awake from Applications. A cup icon appears in your menu bar near the clock.
  4. If macOS asks whether you are sure you want to open it, choose Open. If you do not see an Open button, go to System Settings, Privacy and Security, scroll down, and choose Open Anyway. You only need to do this once.

To have Keep Awake start every time you log in, open its Settings and turn on Open at login (see Settings).

Quick start

  1. Click the cup icon in the menu bar.
  2. Choose Turn On. Your Mac will now stay awake.
  3. Click the cup again and choose Turn Off when you are done.

That is the whole idea. The rest of this guide explains the options.

When Keep Awake is on, the icon fills in and the menu shows a status line, for example On, screen on, 42m left.

The menu bar

Click the cup icon to open the menu. From top to bottom:

Status line

The first line tells you what is happening:

  • Keep Awake, Off means it is not keeping your Mac awake.
  • On, screen on means the screen and the Mac are both staying awake.
  • On, screen can sleep means the Mac stays awake but the display may turn off.
  • It also shows how the current session will end, for example 42m left, until Final Cut Pro quits, or 2 AI agents when AI agents are keeping the Mac awake.

Turn On / Turn Off

Turns Keep Awake on or off. If you have set a keyboard shortcut, it appears here too.

Screen

  • Keep screen on: the screen and the Mac both stay awake. Good for reading, presentations, and dashboards.
  • Let screen sleep: the Mac keeps running (downloads, builds, renders) while the display is free to turn off and save power.

Turn off after

Choose when Keep Awake should switch itself off:

  • Never: stays on until you turn it off.
  • A preset: 15 minutes, 30 minutes, 1 hour, 2 hours, or 5 hours.
  • Custom: enter any number of minutes.
  • When an app quits: pick any open app, and Keep Awake stays on until that app quits. Handy for a long export or render: choose the app doing the work, and your Mac sleeps as soon as it finishes.

Settings and Quit

  • Settings: opens the Settings window (next section).
  • Quit: closes Keep Awake. Your Mac returns to its normal sleep behavior right away.

Settings

Open the menu and choose Settings. Everything you set here is remembered between launches.

General

  • Open at login: turn this on to have Keep Awake start automatically every time you sign in.
  • Global shortcut: set a keyboard shortcut to toggle Keep Awake from anywhere. See Keyboard shortcut.

AI agents

  • Allow AI agents to keep this Mac awake: lets AI coding agents keep your Mac awake while they run a long task. This is on by default, and you can turn it off at any time. See Keep your Mac awake for AI agents.
  • Connect your agent: pick your tool from the menu and copy the one step it shows, so your agent can talk to Keep Awake.

Updates

  • Check for Updates: check for a new version now. Keep Awake also checks on its own in the background.
  • The version number is shown here.

Keyboard shortcut

A global shortcut lets you toggle Keep Awake from anywhere, even when another app is focused.

  1. Open Settings.
  2. Next to Global shortcut, click Set Shortcut (or Change if you already have one).
  3. Press any combination that includes Command, Control, or Option, for example Shift Command E.
  4. The shortcut now turns Keep Awake on and off from anywhere on your Mac.

Keep Awake uses the standard macOS hot key system, so it does not need Accessibility permission. If a combination is already used by another app, pick a different one.

Keep your Mac awake for AI agents

This is the headline feature in version 2.0. If you use an AI coding agent, you have probably come back to a sleeping Mac and a half-finished build. Keep Awake fixes that: your agent can keep the Mac awake while it works, then let it sleep again when it is done.

Behind the scenes, Keep Awake includes a small built-in MCP server (Model Context Protocol). MCP is the common way for AI tools to use outside capabilities, and this one gives your agent two simple abilities: keep the Mac awake, and let it sleep again.

Turn it on or off

AI agent access is on by default. To change it, open Settings, AI agents and use the Allow AI agents to keep this Mac awake switch.

  • When it is on, a connected agent can keep your Mac awake while it works.
  • When it is off, agent requests are ignored, and an agent that asks is told that access is turned off.

You are always in control:

  • Turning the switch off stops every agent at once, even one that is in the middle of a task.
  • Your own on and off always takes priority. If you have turned Keep Awake on yourself, an agent cannot turn it off.

Connect your agent

Open Settings, AI agents, choose your tool from the Connect your agent menu, and click Copy. The window shows the exact step for that tool. The command always points at wherever you installed Keep Awake, so copy it from Settings rather than typing it by hand.

The examples below assume Keep Awake is in your Applications folder.

Claude Code Run this once in Terminal:

claude mcp add keep-awake -- "/Applications/Keep Awake.app/Contents/MacOS/KeepAwake" --mcp

Claude Desktop Add this to ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "keep-awake": {
      "command": "/Applications/Keep Awake.app/Contents/MacOS/KeepAwake",
      "args": ["--mcp"]
    }
  }
}

Cursor Add the same block to ~/.cursor/mcp.json, then restart Cursor.

Antigravity Open Antigravity, go to its MCP servers settings, and add a server with the command /Applications/Keep Awake.app/Contents/MacOS/KeepAwake and the argument --mcp.

Codex CLI Add this to ~/.codex/config.toml:

[mcp_servers.keep-awake]
command = "/Applications/Keep Awake.app/Contents/MacOS/KeepAwake"
args = ["--mcp"]

Any other MCP client Keep Awake is a local (stdio) MCP server. Add it as a command with the argument --mcp:

"/Applications/Keep Awake.app/Contents/MacOS/KeepAwake" --mcp

After connecting, restart the tool if it was already running, so it picks up the new server. Most tools load MCP servers at startup.

Once connected, tell your agent to use it. A line like this in your project instructions is enough: "At the start of a long task, keep this Mac awake, and let it sleep again when you finish."

What works, and what does not

Keep Awake is a local MCP server that runs on your Mac. It works with tools that support local MCP servers, such as Claude Code, Claude Desktop, Cursor, Antigravity, and Codex CLI. It does not work with services that only accept a remote MCP server reached over the internet, such as the ChatGPT website connectors, because those need a public web address rather than an app on your Mac.

How it behaves with agents

Keep Awake is built so it cannot get stuck on:

  • More than one agent: several agents can keep your Mac awake at the same time. Your Mac stays awake until the last one is finished, so one agent cannot cut another one short.
  • An agent that stops or crashes: if an agent is force quit and never says it is done, its hold clears on its own a short while later. An agent that vanishes can never keep your Mac awake forever.
  • No timeout for agents: while an agent is working, your Mac stays awake with no countdown. The "Turn off after" timer applies only to sessions you start yourself.

How Keep Awake decides to stay awake

Keep Awake uses the same macOS power mechanism as the caffeinate command, with no background tricks. Your Mac stays awake while any of these is true: you turned it on, a timer or watched app is still active, or an agent is holding it (when AI agents are allowed). The request is released the moment you turn it off, the timer ends, the watched app quits, or you quit Keep Awake. That is why it cannot get stuck keeping your Mac awake.

Lid closed: like caffeinate, Keep Awake keeps your Mac awake while it is idle. It does not keep a laptop awake with the lid shut, which is a separate macOS behavior.

Updates

Keep Awake updates itself. It checks for new versions in the background and offers them to you inside the app, so there is no need to download anything by hand. You can also check any time from Settings, Check for Updates.

Privacy

Keep Awake keeps to itself. It does not collect your data, show ads, or send your activity anywhere. It connects to the internet only to check for app updates. The AI agent feature works entirely on your own Mac through small local files, with nothing sent to us or to anyone else.

Troubleshooting

I do not see the cup in the menu bar. Open Keep Awake from your Applications folder. If your menu bar is full, macOS may hide some icons. Try widening the menu bar by quitting another menu bar app, or use a menu bar manager to reveal hidden icons.

My keyboard shortcut does not work. Another app may already use that combination. Open Settings, choose Change, and pick a different one that includes Command, Control, or Option.

My agent says AI access is turned off. Open Settings, AI agents, and turn on "Allow AI agents to keep this Mac awake." If it is already on, make sure your tool is pointed at the exact command shown under "Connect your agent", and restart the tool.

My agent cannot connect at all. Confirm your tool supports local MCP servers (see What works, and what does not). Copy the command from Settings rather than typing it, since the path must match where Keep Awake is installed. Restart the tool after adding the server.

My Mac still went to sleep. Check the menu status line to confirm Keep Awake is on. Note that closing a laptop lid is a separate macOS behavior that Keep Awake does not override.

Uninstall

  1. Open the Keep Awake menu and choose Quit.
  2. Drag Keep Awake from your Applications folder to the Trash.
  3. If you turned on Open at login, macOS removes that entry automatically when the app is gone.

Get help

Questions or feedback are welcome. Visit https://speranda.com/tool.html?tool=keep-awake or reach us at speranda.com.