awk-mcp

Keep your Mac awake while your AI agent works, and let it sleep again once the agent is done or is waiting on you.

A tiny MCP server with no dependencies. The server is one file of about 190 lines, and it ships with an agent skill that tells the agent when to use it. It wraps the caffeinate command built into macOS. Your agent calls awake_start when it begins a long task. The Mac stays awake until one of these happens:

When the idle timeout or the cap releases the hold, you get a macOS notification.

macOS only. It needs Node.js 18 or newer and /usr/bin/caffeinate, which ships with macOS.

Install

Claude Code plugin (recommended: server + skill)

The repo is also a Claude Code plugin marketplace. Installing the plugin gives you the MCP server and the keep-awake skill, which teaches the agent when to start, ping and stop:

claude plugin marketplace add yhauxell/awk-mcp
claude plugin install awk-mcp@awk-mcp

Or inside a session: /plugin marketplace add yhauxell/awk-mcp, then /plugin install awk-mcp@awk-mcp. Restart the session afterwards.

If you already registered the server by hand (claude mcp add … awake), remove that entry (claude mcp remove awake -s user) so the agent doesn't see two copies of the tools.

Claude Code, MCP server only

claude mcp add --scope user awake -- npx -y github:yhauxell/awk-mcp

Or from a local clone:

git clone https://github.com/yhauxell/awk-mcp.git
claude mcp add --scope user awake -- node "$PWD/awk-mcp/server.mjs"

Any MCP client (Claude Desktop, Cursor, …)

{
  "mcpServers": {
    "awake": {
      "command": "npx",
      "args": ["-y", "github:yhauxell/awk-mcp"],
      "env": {
        "AWAKE_IDLE_MINUTES": "30",
        "AWAKE_MAX_MINUTES": "240",
        "AWAKE_DISPLAY": "false"
      }
    }
  }
}

Related MCP server: macos-desktop-control

Tools

awake_start

Starts keeping the Mac awake. If a session is already active, this call replaces it. All parameters are optional.

awake_ping

Tells the server you're still working, which resets the idle timer. Any tool call to this server resets it too.

awake_stop

The task is done. The Mac can sleep normally again.

awake_status

Returns whether a hold is active, its settings, the seconds left until idle release and until max release, and why the last hold ended.

Configuration

These environment variables set the defaults. Per-call parameters override them, and invalid values fall back to the built-in default with a warning on stderr.

Telling your agent to use it

Agents get guidance on three layers:

1. Server instructions (always on). During the MCP handshake the server sends a short instructions string. Clients that support it, including Claude Code, put it in the agent's system prompt: start before long work or when the user steps away, ping during long silent commands, stop when done or before asking the user something.

2. The keep-awake skill (installed with the plugin). The full playbook: which parameters fit which situation, the ping cadence, when to release, what it can't do, and what to say if the tools are missing. It's a standard SKILL.md, so you can also copy skills/keep-awake/ into any agent that reads Agent Skills.

3. Your own rules (optional). To make it unconditional, add something like this to CLAUDE.md, AGENTS.md, or a system prompt:

Before any task likely to take more than a few minutes, call `awake_start`.
During long silent steps (builds, test suites) call `awake_ping` at least every 20 minutes.
Call `awake_stop` when the task is finished.

What "awake" and "unlocked" mean

• display: false blocks only idle system sleep (caffeinate -i -m). The screen can still turn off and lock, but processes, downloads and agents keep running.

• display: true also keeps the display on (caffeinate -d) and declares user activity every 30 s (caffeinate -u). The idle screensaver doesn't start, so auto-lock never triggers. On the author's Mac the screensaver was set to 5 minutes. With no keyboard or mouse input for 353 s, it never started.

• It can't unlock a Mac that's already locked, and it doesn't prevent a manual lock (⌃⌘Q, hot corners, closing the lid).

• Closing the lid still sleeps the Mac unless it's in clamshell mode with an external display.

Idle timeout caveat

The server can't tell "the agent is waiting for the user" apart from "the agent is busy with a 40-minute build and not calling me". All it sees is the time since the last call. Set idle_timeout_minutes longer than your longest silent step, or tell the agent to awake_ping during long work.

Security

• No network access, no dependencies, no file writes. The server only reads JSON-RPC from stdin and writes to stdout and stderr.

• No shell: child processes run with spawn using fixed absolute paths (/usr/bin/caffeinate, /usr/bin/osascript). Tool arguments never reach a command line, and the notification text goes to osascript as an argument, not as script source.

• Validated input: numbers must fall within (0, 1440], and the reason string is length-capped.

• No stuck holds: a crash or a killed server can't leave your Mac awake indefinitely, because caffeinate watches the server's PID and exits with it.

How it works

awake_start starts one long-lived process: caffeinate -i -m [-d] -t <max seconds> -w <server pid>. The server also runs two JavaScript timers, one for idle and one for max. Whichever fires first kills that process. With display: true, a 30-second interval runs a short caffeinate -u -t 1 to reset the user-idle clock. You can see the live assertions with:

pmset -g assertions | grep caffeinate

Development

node test.mjs

The tests drive the server over stdio and check real power assertions with pmset -g assertions and pgrep. They cover the handshake and notifications, start/stop, display vs. system-only, restart without stacking, idle timeout and ping extension, the max cap, stdin EOF, kill -9 cleanup, and input validation. They take about 20 s, and nothing stays held afterwards.

License

MIT