Keepresso
Keep your Mac awake, on your terms, with smart triggers, presets, timed
sessions, and closed-display mode in a clean, native menu-bar app, built on a
modern foundation for the next decade of computing.
keepresso.com
Keepresso is a native Swift + SwiftUI menu-bar app. It uses macOS power
assertions (IOPMAssertion) to prevent system and display sleep, and layers on
condition-based triggers so your Mac only stays awake when it actually should.
It lives quietly in the menu bar, no Dock icon, no clutter.
Features
- ☕ Keep awake, your way. Prevent system sleep and/or display sleep as
independent toggles, indefinitely, for a timed session (presets or any custom
duration), or until a wall-clock time ("until 18:00", today or tomorrow).
- 🌙 Yield the screen saver. Let the screen saver or display sleep kick in
after _N_ minutes idle while the system itself stays awake.
- 🔅 Dim, don't sleep. On a long held session, let the built-in display drop
to its dimmest a few minutes after you step away, staying awake but dark, then
snap back to your brightness the moment you return or the session ends. Kinder
to the panel and the battery on overnight sessions than a screen left fully lit.
- 🟢 Keep me active. Keeping the Mac awake does not by itself keep you
present. Meeting and chat apps, remote desktop, VDI, cloud gaming, and many
other tools still treat a quiet keyboard as idle: they mark you away,
disconnect, or time out. Optionally stay active too, and pick how: a
prompt-free power/cursor warp, or F15 every 60 seconds, Shift, a specified
key, or a posted mouse move when the software only notices a real key or
mouse. Those methods request Accessibility only when you pick them. It only
steps in once you've been idle a few seconds, so it never types or nudges
while you're using the Mac. Off by default.
- ⚡ Trigger engine. Stay awake only while charging or on battery, an external
display is connected, you're on a chosen Wi-Fi network, **a VPN is
connected, the camera or microphone is in use, audio is playing**, a
chosen Bluetooth device is connected (headphones, a controller), a
calendar event is in progress, a specific app or process is running, a
chosen volume is mounted, CPU usage sits above a threshold (builds,
renders, training runs), network throughput stays above a threshold (a
large download, upload, or sync), a download is in progress in a folder you
choose (keep awake until it finishes), a game is in front, or during a
scheduled time window (weekdays 9:00-18:00, overnight hours). Combine
conditions with any (OR) or all (AND). A one-click "Pause Triggers"
in the menu bar stops brewing without touching your rules.
- 🤖 Agent-aware. The "AI agent is working" condition keeps the Mac awake
while a coding agent (claude, cursor, codex, antigravity, gemini, grok, aider,
goose, pi, hermes, kilo, opencode, dsh, muse, devin, qwen, kimi, and friends) is actually working, and lets it sleep once every
session goes quiet, after a grace you choose. Agents that stream a transcript
to disk prove their work directly, even through long zero-CPU network waits.
The rest are judged on the CPU of their processes and tool calls against each
session's own learned idle level. **Claude Code, Cursor, Codex, Grok, and
Antigravity** can report their state exactly, via an opt-in hook integration
you connect in one click: a session is working when the tool says it is, a
pending permission prompt counts as working (so the Mac waits for your
answer), and background subagents count too. That covers the agents built into
the Cursor and Antigravity apps, which run inside the editor and have no
process of their own to watch, and each chat inside one editor is tracked on
its own. The menu lists every session with a live working / idle state and
where it runs.
- ⏰ Wake for scheduled AI runs. Keepresso reads the recurring tasks your
local AI tools schedule (Claude Desktop routines, Codex automations,
tokenstat.ai), wakes the
Mac a few minutes before each run, and holds it awake long enough to finish,
even with the lid shut. It reads only the schedule and name, never the prompt,
ignores cloud routines (those run on the vendor's servers, no wake needed), and
you switch on the tools you want woken for. A run that needs longer can hold a
lease until it's done.
- ⏹️ Stop in 15, one click. A row of quick "Stop in" buttons (15 min, 30 min,
1 h out of the box, editable) turns a running session into a timed one, so the
Mac goes back to sleeping on its own without you remembering to toggle off.
Optionally get a heads-up a few minutes before any timed session ends.
- 🎥 Never sleeps mid-meeting. The camera/microphone conditions catch every
meeting app at once, including calls running in a browser tab, and read only
the device's in-use state (the green-dot signal), never the stream, so no
camera or microphone permission is ever requested. You can also scope the
microphone to one app, so only a real call in Slack, Discord, or Zoom holds the
Mac awake, not any app that happens to open the mic.
- 🎮 Game-aware. The "Playing a game" condition spots apps that declare a
games category, anything running from a Steam library (many Steam games
skip the declaration), and the cloud and game-streaming clients: **GeForce
NOW, Boosteroid, Parsec, Moonlight, Shadow**. A five-minute grace means
alt-tabbing to Discord doesn't drop the session. A controller condition
counts any connected gamepad, DualSense, Xbox, and Steam Controller
included (detected permission-free even though macOS reports it as a
keyboard and mouse), and a Steam download condition holds the Mac
awake while a game actually downloads, releasing when it finishes or you
pause it. While you play, opt-in comforts keep the display awake during
controller-only sessions and give the game high CPU priority through
the administrator helper, restored when the bout ends.
- ⌨️ Keyboard Cleaner. Lock the keys from the panel or the icon menu so you
can wipe the keyboard without typing into Slack. Top-row Mac keys (Mission
Control, Spotlight, Dictation) are included. The pointer stays live. No
Accessibility prompt.
- 🌐 Public Wi-Fi. When a cafe or airport network associates but never
shows a login page, a Headless-style window diagnoses the captive portal and
offers Open login page, Flush DNS, and a Wi-Fi cycle. Opening it does not
ask for Location or an administrator password.
- 📶 Gaming & Streaming Setup. macOS hops the Wi-Fi radio off-channel for
AWDL (AirDrop, Handoff, Sidecar) about once a second, which shows up as
50-100 ms ping spikes mid-game or mid-stream. A dedicated window diagnoses
it with a built-in jitter test, and fixes it with a session-scoped
AWDL pause: no password at all with the administrator helper installed
(once per launch without it), instant toggling, and everything restores
itself the moment you stop (even after a crash). An
automatic mode watches for a game (or a cloud-gaming app) on its own with
no trigger setup, authorizes once up front so it never pops a password dialog
over a running game, and shows a live status with a grace countdown when a
game closes. Optional notifications when it pauses and resumes. Plus
radio-hygiene checks: wired network, Wi-Fi channel alignment with AWDL's
social channels (44 in the EU, 149 in the US and Canada), Bluetooth, Game Mode.
- 🎛️ Presets. Apply a named trigger bundle in one click, built-in (AI Agent,
Gaming, Cloud Gaming, Meetings, Remote Control, On AC Power, External
Display Connected, Remote Session (SSH), Backup Running, Media Render) or
your own saved rule sets. Deleted a built-in? "Restore default presets"
brings it back.
- 👋 First-run setup. A welcome window on a new Mac points out that Keepresso
lives in the menu bar (no Dock icon) and sets you up in one click for how you
work: agentic coding, gaming and streaming, meetings and calls, or remote
access. Reopen it any time from Preferences.
- 🧩 Desktop widgets and a Control Center toggle. A small widget that's a
one-tap toggle (the brand cup fills and steams while brewing, with a live
countdown), a medium widget with Start/Stop and Pause/Resume Triggers
buttons, and on macOS 26 a Keep Awake control for Control Center.
- 🔍 Awake explainer. The Activity pane shows every app's live power
assertions, a readable pmset -g assertions, so you can see exactly what's
preventing sleep (whoever's doing it), a seven-day held-awake summary, and a
decision log of why each Keepresso session started or stopped that survives
relaunch. The menu bar even names another app that's holding the Mac awake
("Held by Google Chrome") when Keepresso itself is idle.
- 🪪 Auto app detection. Caffeinate while listed apps run or are frontmost,
with an optional grace period before it lets go.
- 🔋 Battery-aware auto-pause. Let the Mac sleep once charge drops below a
threshold you choose, even mid-session, so it never runs the battery flat.
- 🌡️ Thermal safety net. Holding a Mac awake through heavy load can also
hold in the heat, so Keepresso can watch it: macOS's own thermal pressure
(works on every Mac) or specific temperature sensors picked from a live
list. If the reading stays over your threshold for a sustained time it
escalates, first (optionally) boosting the fans to a chosen strength, never
below what the system already chose, then pausing the session so the Mac
can cool, with a notification saying why. Everything restores itself once
temperatures recover. A built-in "Test Fans" check proves the fan path
end to end in about 12 seconds ("All good. Fan 1: 0 → 4800 rpm"), so you
can trust the boost before a heavy render needs it. Watching and pausing
work everywhere. The fan boost runs through the administrator helper, so
it's silent and never prompts.
- ⏱️ Menu-bar countdown. An optional live countdown next to the cup icon for
timed sessions.
- ⌨️ Global hotkey. A system-wide keyboard shortcut to toggle keep-awake from
any app, recorded in Preferences (Carbon-based, so no Input Monitoring or
Accessibility permission).
- 🚀 Start on launch. Optionally begin a keep-awake session the moment
Keepresso launches, for an always-on Mac that shouldn't need a rule.
- 💾 Export and import. Back up your settings, triggers, and presets to a JSON
file, or move them to another Mac, from Preferences > General. The file is
version-stamped and validated on import.
- 🔗 Shortcuts and URL scheme. Native Shortcuts actions (Start, Stop,
Toggle) for Shortcuts, Spotlight, and Siri, plus a URL scheme for Raycast,
Alfred, or a shell script: keepresso://start?duration=60,
keepresso://start?until=18:00, stop, or toggle.
- 💻 Closed-display mode. Keep running with the lid shut and no external
display, on power or battery, for an always-on Mac or one you carry mid-task.
What the screen itself does is your choice: turn it off, keep it powered at
zero brightness so a remote session stays live, or leave it alone. An optional
"Only while brewing" mode ties it to the session instead of leaving it on
globally: on when a keep-awake session starts, off when it ends (or the app
quits, even after a crash), with the password asked once per app run, or
never with the administrator helper.
- 📱 Hotspot fallback. In Preferences > General, opt into a selected Wi-Fi
hotspot when the Mac loses its network connection. Scope it to active
keep-awake sessions (the default), closed-display mode, or whenever Keepresso
runs. Choose the delay, retry interval, battery minimum, and connection
notifications. Passwords stay in Keychain and are never included in settings
backups. Requires Location access and a broadcasting, secured hotspot. For
iPhone discovery, use macOS Wi-Fi settings > Ask to join hotspots > Automatic.
Keepresso does not enable the phone's hotspot remotely, interrupt an existing
route, or switch away from a connected hotspot with no internet access.
A network handoff can briefly interrupt requests; agents must handle their
own reconnects.
- 🍃 Closed-lid Low Power Mode. An optional switch in General's
closed-display section temporarily selects Low Power Mode while the lid is
shut and the sleep override is active. Battery only by default; optionally
include plugged-in use. The administrator helper preserves battery and
adapter settings independently, confirms each write, and restores them when
the lid opens, the override ends, or the app disconnects. Its restore journal
also survives daemon restarts. The status explains what it is waiting for.
- 🌀 Closed-lid fan floor. On supported Macs with fans, opt into a minimum
fan speed while closed-display mode is active and the lid is shut. Starts at
50% of the fan range, adjustable from 10% to 100%. This is independent of the
thermal heat boost and pause settings: a heat boost can raise the floor, then
return to it when the Mac cools. Fanless Macs keep the existing thermal pause
behavior. Disarming or quitting restores automatic fan control.
- 🔑 One password, ever. An optional administrator helper, a small
system service installed from Preferences > General (or the welcome screen),
handles the privileged switches for Keepresso: closed-display mode, the
thermal fan boost, and the AWDL pause become instant and silent, with no
password prompt on any launch. macOS asks for your password once, when you
approve the helper under Login Items, and the approval survives restarts
and updates, and app updates replace the service automatically, never a
reinstall. The helper can only flip those specific switches, restores
everything if the app quits or crashes, puts the keepresso CLI on PATH
for DMG installs, and can be removed at any time. Without it, everything
still works the old way, with a once-per-run prompt (now always announced
by a notification), except the fan boost, which stays off rather than ever
prompting from a background safety action.
- 🔔 Reminders, end actions, and event hooks. A "still brewing" notification
(with an optional sound) after _N_ minutes, one-time or recurring, so a
forgotten session can't quietly drain the battery. When a session ends on its
own (a timer expiring, triggers dropping), optionally notify, then sleep the
display, lock the screen, start the screen saver, or sleep the Mac. And when
something happens (session start/end, trigger fire/release, agent went idle,
thermal stage, battery pause), run a Shortcut, POST a webhook, or a shell
command, handy for a push to your phone when an overnight agent finishes.
Schedule a system wake through the administrator helper and optionally start
keep-awake when the Mac comes back (wake, work, sleep).
- 💽 Disk keep-alive. Periodic no-op disk I/O to stop an external drive or NAS
from spinning down.
- 🖥️ Headless Setup checklist. Probes the system settings an always-on,
headless Mac needs (sleep, auto-restart, auto-login, FileVault, remote access)
and guides you to fix each one.
- 🖼️ Headless virtual display (experimental). On a Mac with no monitor,
create a higher-resolution HiDPI virtual display so Screen Sharing and VNC look
crisp instead of a fuzzy 1920×1080. Off by default; uses a private macOS API,
so it's a no-dummy-plug software alternative you should treat as experimental.
- ✨ Native and quiet. A menu-bar agent with an animated cup while brewing, a
live summary of what's holding the session on, a Liquid Glass app icon (Icon
Composer, with light, dark, and tinted appearances), and Liquid Glass window
styling on macOS 26+. The dropdown's glass is yours to tune, from frosty to
fully clear (Preferences > General > Appearance).
- 🌍 Fifteen languages. English, German, Spanish, French, Hungarian, Italian,
Japanese, Korean, Russian, Brazilian Portuguese, Turkish, Polish, Ukrainian,
Simplified Chinese, and Traditional Chinese, across the menu, every window,
notifications, VoiceOver labels, and the widgets. Pick one in Preferences or on
the Welcome screen, or follow the system language (the default).
- ⬆️ Self-updating. Built-in auto-updates via Sparkle,
with an EdDSA-signed appcast on GitHub Releases.
Screenshots
General: keep-awake toggles, launch at login, a global shortcut, your language
|
Trigger engine: combine conditions with any or all, or apply a preset
|
Awake explainer: every app's live power assertions, plus why each session started or stopped
|
Headless virtual display: crisp Screen Sharing on a Mac with no monitor
|
Adding a condition: grouped menus for power and display, network and devices, apps and activity, with Claude Code connected
|
Built for the agentic era
The only app you'll ever need for a headless Mac setup, whether it's running
AI agents, a server, a render farm, or anything reachable over HTTP or SSH.
Keepresso fits the way Macs are used now, and where they're headed:
- 🤖 AI agents. Keep a Mac awake and reachable so agents can operate it around
the clock without it dozing off mid-task.
- 💻 MacBooks on the go. Closed-display mode keeps work running on power or
battery while you pack up and move.
- 🧑💻 Builders and vibe coders. Long builds, training runs, and overnight jobs
finish instead of getting cut short by sleep.
- 🏢 Business and enterprise, no charge. Headless Mac minis and Mac Studios
powering local LLMs, agent fleets, CI, or a render farm stay up without a
license fee.
- 🎬 Studios. Long renders and exports run to completion, untended.
- 🎮 Gamers and streamers. Sessions stay awake while you play (native,
Steam, or cloud), and the AWDL pause smooths out the once-a-second ping
spikes that stutter cloud gaming and live streams.
The use cases are effectively limitless. Modern UI, a solid and well-tested
foundation, and a quiet must-have for the next decade of computing.
Automation leases, CLI, and MCP
Any tool can hold the Mac awake for exactly the lifetime of a task through a
bounded lease: acquire with a TTL, heartbeat while working, release when
done. Leases union, a crashed tool's lease simply expires, and after the
last one ends the Mac can sleep again (running your configured
end-of-session action). Works for AI agents, render scripts, backup jobs,
anything that can run a command:
ID=$(uuidgen)
keepresso lease acquire --id "$ID" --tool render --task "overnight export" --ttl 600
... long work with periodic: keepresso lease heartbeat --id "$ID"
keepresso lease release --id "$ID"
MCP-capable agents get the same operations from the bundled server; point
your MCP configuration at:
/Applications/Keepresso.app/Contents/Helpers/keepresso-mcp
A ready-to-copy agent skill ships in the app at
Contents/Resources/AgentSkill/keep-awake. Agents can also read the system
wake schedule with keepresso wake status, and, if you flip the default-off
switch in Preferences ▸ Automation, schedule wake-ups with
keepresso wake set.
Install
Homebrew:
brew install --cask gyorgysh/keepresso/keepresso
Manual: download the latest signed, notarized DMG from
keepresso.com or
Releases, drag Keepresso to
Applications, and launch it.
Either way, Keepresso keeps itself up to date from there.
Using Keepresso
Click the cup in the menu bar to open Keepresso. Right-click (or control-click)
it for a compact context menu with the app entries: Preferences, Headless
Setup, Gaming & Streaming, Keyboard Cleaner, Public Wi-Fi, About, Check for
Updates, and Quit.
- Quick toggle. Flip Keep awake on or off and pick a duration:
indefinitely, a preset (15 minutes, 1 hour, 4 hours), any custom duration, or
until a time of day. The cup fills and animates while brewing.
- Customize the menu. Open Customize Menu… in Preferences > General >
Menu bar for a live preview beside the editor. Enable **Customize menu
sections**, then start with
Minimal, Compact, Balanced, Lid controls, Brewing controls,
Status only, or Detailed, then hide, reorder, pin, or move any of the 39
controls between groups. Choose spacing, panel width, status style, group
headings and disclosures, trigger and agent detail, and menu-bar text. Session
action buttons use the accent color by default, while dropdowns and app links
stay neutral. Appearance > Control style > Clear style makes the session
actions neutral too, with the same button shape and centered label. All presets
keep the standard 280-point width. Settings and tools start collapsed; the
session controls adapt to manual and trigger
sessions. The two small switch variants add just closed-display mode or
Only while brewing to Compact.
Status only shows information without session buttons. Preview controls cannot
change a session or feature setting.
“Show less” can retain pinned controls, the first few groups, or everything.
Optional quick controls include manual sessions while triggers are running,
display sleep, keep-active, reminders, presets, and end actions.
Customization is off by default. Enabling it keeps the standard menu until
you choose a profile or edit a layout option. Disabling it restores that menu
while retaining your custom layout. Layout changes preserve feature settings
and are included in configuration backups. Preferences and Quit remain
available by right-click and keyboard shortcut. Active sleep overrides and
safety warnings remain visible, with their settings reachable in Preferences.
- Show less. The disclosure row at the bottom of the panel folds the option
toggles and app entries away, leaving just the status and the keep-awake
controls. Keepresso remembers the choice, and everything hidden stays
reachable from the right-click menu.
- Keep awake with lid closed. Toggle it right from the menu before you shut
the lid or unplug. It flips a system setting (pmset disablesleep), so it
needs administrator rights: silent with the helper installed, one password
ask without it. Works on power or battery; turn it off when you're done, on
battery in a bag it can drain and heat up. Or set it to **"Only while
brewing"** in Preferences > General and it follows the session on its own:
on at session start, off at session end or app quit.
- Preferences (⌘,) holds the set-and-forget configuration, in tabs:
- General: what to keep awake, the administrator helper, menu-bar
countdown, battery auto-pause, closed-display mode, launch at login,
settings backup (export/import), and the welcome screen.
- Triggers: turn on rule-based activation, apply a preset, and build your
rule set.
- Reminder: a one-time or recurring "still brewing" alert, with a sound,
plus end notifications and the ending-soon warning.
- Automation: end-of-session actions, outbound event hooks, and scheduled
wake (with optional wake-and-brew).
- Disk: choose a volume to keep spun up and how often to touch it.
- Display: create an experimental high-resolution headless virtual display.
- Activity: what's keeping the Mac awake right now, a weekly held-awake
summary, and why each session started or stopped (persisted across relaunch).
- Headless Setup checks that an always-on Mac (say a Mac mini with no display)
is configured to stay reachable, and links you straight to the right settings.
- Gaming & Streaming diagnoses the once-a-second Wi-Fi lag spikes AWDL
causes (jitter test), pauses AWDL for the session with one toggle, and
checks the radio hygiene around it: wired network, Wi-Fi channel, Bluetooth,
Game Mode.
- Keyboard Cleaner locks the keys so you can wipe the Mac, including the
top-row special keys. Unlock is a click. A crash or quit puts the mapping back.
- Public Wi-Fi diagnoses captive portals that never show a login page and
offers Open login page, Flush DNS, and a Wi-Fi cycle.
Keepresso has no Dock icon by design. Everything lives in the menu bar.
Driving it from Shortcuts or a script
Keepresso ships native Shortcuts actions: Start Keeping Awake (optionally
for _N_ minutes), Stop Keeping Awake, and Toggle Keep Awake, usable from the
Shortcuts app, Spotlight, and Siri.
It also registers a keepresso:// URL scheme so Raycast, Alfred, or a shell
script can start or stop a session without opening the menu:
open "keepresso://start" # indefinite session
open "keepresso://start?duration=60" # timed session, in minutes
open "keepresso://start?until=18:00" # until a wall-clock time (24h HH:MM)
open "keepresso://stop"
open "keepresso://toggle"
Either way, if triggers are on they pause first (same as the menu's Pause
Triggers), so the command actually takes effect.
The keepresso command-line tool
The app bundle ships a caffeinate-style CLI. The Homebrew cask links it onto
your PATH; on a DMG install, the administrator helper creates the
/usr/local/bin/keepresso link for you. It drives the app for session
commands and can also hold its own assertion when you need to block in a
pipeline:
keepresso start --for 90 # tell the app to brew for 90 minutes
keepresso stop # end the session
keepresso status # exit 0 awake, 1 not, 2 app not running
keepresso status --json # machine-readable, jq-friendly
keepresso -t 3600 # hold an assertion itself for an hour
keepresso -w $! # stay awake until a process exits
keepresso -d -i # also keep the display awake, until Ctrl-C
keepresso -u # wake the display now
The standalone holds work even when the app is not running; keepresso help
lists everything. Installed from a DMG instead of Homebrew? Symlink it
yourself: ln -s /Applications/Keepresso.app/Contents/Helpers/keepresso /usr/local/bin/.
Why not the Mac App Store?
The App Sandbox blocks the IOPMAssertion power APIs Keepresso depends on, so
it's distributed outside the store, as a direct, notarized DMG download.
Building from source
Keepresso uses XcodeGen to generate
the Xcode project from project.yml (the .xcodeproj is not
checked in), and Swift Package Manager for the testable core
(KeepressoCore).
Requirements: macOS 14+, Xcode 16+, xcodegen (brew install xcodegen).
git clone https://github.com/gyorgysh/keepresso.git
cd keepresso
./scripts/run.sh # generate the project and open it in Xcode (⌘R to run)
Working on the core logic
The sleep-control state machine lives in KeepressoCore and is fully unit
tested, independent of any UI:
swift build # build the core library
swift test # run the test suite (requires the full Xcode toolchain)
How it works
Two layers, by design:
KeepressoCore is a SwiftUI-free SwiftPM library: the SessionController
state machine plus protocol seams over every system touchpoint (power
assertions, power source, displays, network, workspace, disk, notifications).
This is where behavior lives and where the tests are.
Keepresso is the thin SwiftUI MenuBarExtra app: views and lifecycle
glue wired to the real system backends.
The controller doesn't run its own timer; the app ticks it once a second. Tests
advance a fake clock and inject fakes for the system seams, so the logic is
verified without touching real hardware.
Scripts
scripts/run.sh: generate the project and open it in Xcode.scripts/make-icon.swift: regenerate the app icon asset catalog.
See docs/BUILDING.md for a full build walkthrough and
CLAUDE.md for the architecture and contributor workflow.
Contributing
Issues and pull requests are welcome. New behavior goes in KeepressoCore behind
a protocol seam with tests, then a thin SwiftUI layer in the app.
License
GNU GPL v3.0 © 2026 Keepresso contributors.
Keepresso is free software: use it, study it, fork it, and contribute back. The
copyleft terms mean any distributed version (including forks and modifications)
must stay open-source under the same license, so nobody can take it closed and
ship a proprietary product from it.
If Keepresso is useful to you, you can support its development.
