Let AI agents and scripts keep your Mac awake with automation leases

An agent that runs a long job overnight needs the Mac awake while it works, and asleep when it is done. A plain "keep awake on" gets the first half and fails the second: if the tool crashes or forgets to turn it off, the Mac stays pinned awake forever. Automation leases fix that. A script or an AI agent acquires a lease with a time limit, keeps renewing it while the work runs, and releases it at the end. If the tool dies mid-job, the lease simply expires and the Mac can sleep again. Nothing is left holding the machine up by accident.

Keepresso ships the whole stack for this: the keepresso lease commands, an MCP server any MCP-capable agent can call, and a bundled agent skill you can install in one click.

Detection watches, a lease speaks

Keepresso already has an AI agent trigger that detects when a coding agent is actually working: Claude Code can report its true state through an opt-in hook, and the known agents (claude, codex, gemini, and friends) are judged by the activity of their own processes. That side needs no setup in the agent at all, Keepresso simply watches.

But detection can only cover the agents Keepresso knows how to recognize, and new ones appear every week. A lease flips the direction: instead of Keepresso guessing, the agent itself tells Keepresso when it needs the Mac awake, for what, and for how long, then keeps proving it is still alive. Any tool that can run a command or call an MCP server can do it, whatever it is called and however it works inside. The two compose nicely: detection covers the everyday sessions you did not think about, leases cover the deliberate long jobs and everything detection cannot see.

Why a lease instead of keepresso start

keepresso start is a fine manual switch, but automation wants different guarantees:

• Bounded. A lease has a TTL the owner must keep renewing, and a maximum lifetime (capped at 7 days) that heartbeats can never extend. A runaway job cannot hold the Mac awake past its ceiling.
• Self-healing. No heartbeat, no hold. A crashed script's lease expires on its own.
• Shared cleanly. Several tools can hold leases at once. Keepresso unions them and lets the Mac sleep after the last one ends, running your end-of-session action then, not before.
• Visible. Every live lease shows in the menu with its countdown, named after the tool and task that took it.

The lease lifecycle

Acquire a lease when the job starts. You pick the id (a UUID), name the tool and the task, and set the TTL in seconds:

ID=$(uuidgen)
keepresso lease acquire --id "$ID" --tool my-script --task "nightly render" --ttl 600

Heartbeat before half the TTL elapses, on a loop for as long as the work runs. A heartbeat can also adjust the TTL:

keepresso lease heartbeat --id "$ID"            # renew with the same TTL
keepresso lease heartbeat --id "$ID" --ttl 300  # renew and shorten it

Release when the job is done, so the Mac does not wait out the rest of the TTL:

keepresso lease release --id "$ID"

And list what is live, yours and everyone else's:

keepresso lease list --json

Every command takes --json for machine-readable output, and the exit codes are made for scripts: 0 ok, 2 the app is not running, 3 the lease was not found or already ended, 4 leases are switched off in Preferences.

Leases are governed by a switch under Preferences, Automation, on by default. Turn it off and every acquire is refused with exit code 4, so automation can never override your choice.

See and stop them from the menu

Live leases appear in the menu panel's status card with a countdown each. You stay in charge: Stop ends them all at once, and the Mac is free to sleep again.

Teach your agent in one click

You do not have to explain any of this to your agent by hand. The app bundle ships a ready-made keep-awake skill that teaches an agent the whole protocol, both the keepresso command line and the MCP server, plus when to use it: before a long build, render, download, or overnight run. Under Preferences, Automation, install it straight from disk into your agent's skills folder. For agents without one, Keepresso copies the full skill as paste-ready instructions instead: paste them into the agent once and the protocol is learned, or save them into a global config file your agent always reads, such as CLAUDE.md or AGENTS.md, so every future session already knows how and when to hold the Mac awake. The skill also lives in the bundle at Keepresso.app/Contents/Resources/AgentSkill/keep-awake if you would rather wire it up yourself.

The MCP server

For agents that speak the Model Context Protocol, the bundle ships keepresso-mcp:

/Applications/Keepresso.app/Contents/Helpers/keepresso-mcp

It exposes tools to acquire, heartbeat, release, and list leases, read Keepresso's status, and read the system wake schedule. MCP is an open protocol, so this is not limited to coding agents: any MCP-capable app can hold its own lease and keep the Mac alive while it works. Preferences, Automation has setup snippets ready to copy for Claude Code, Gemini CLI, Grok, and Codex. For Claude Code it comes down to one command:

claude mcp add keepresso -- /Applications/Keepresso.app/Contents/Helpers/keepresso-mcp

Wake schedules for automation, opt-in

Automation can also read when the system is next scheduled to wake, and, if you allow it, change that schedule:

keepresso wake status                          # always allowed, for anyone
keepresso wake set --at "2026-07-24 07:30"     # one-shot wake
keepresso wake set --repeat MTWRF --time 07:30 # repeating wake
keepresso wake clear

Reading is always allowed. Changing the schedule works only while Allow automation to change the wake schedule is on under Preferences, Automation. It is off by default, because a scheduled wake is a system-wide change applied by the administrator helper. The MCP server carries the matching tools under the same rule.

What you need

• Keepresso 1.17 or newer. Install steps: getting started.
• For the CLI on a DMG install, link the command once.
• For wake-schedule changes, the administrator helper and the opt-in switch above.

Related

• Keep your Mac awake from the command line covers the rest of the keepresso CLI.
• Keep your Mac awake during long builds shows the trigger-based approaches for jobs you run yourself.
• Running agents on an always-on Mac? MyAgens gives it a crew of Claude Code agents you command from Telegram.