A cup button in the macOS 26 Control Center: while it is on, the Mac does not go to sleep.
A replacement for keeping a terminal open with caffeinate -d -i.
- On:
cup.and.heat.waves.fill(cup with steam), sleep is prevented. - Off:
cup.and.saucer(empty cup), normal sleep behavior.
Requires macOS 26 (Tahoe) or later, Apple Silicon or Intel.
-
Download
CoffeeControl-<version>.zipfrom Releases, unzip it and moveCoffeeControl.appto/Applications(or~/Applications). -
The app is ad-hoc signed and not notarized (that needs a paid Apple Developer account), so Gatekeeper blocks it at first. Allow it once:
xattr -dr com.apple.quarantine /Applications/CoffeeControl.app
Or: double-click the app, close the "not opened" dialog, then System Settings → Privacy & Security → "Open Anyway".
-
Open the app once. Nothing appears: it is a background agent with no window or Dock icon. This registers the control with macOS.
-
Control Center → Edit Controls → search "Coffee" → drag the cup in. If the search finds nothing, open the widget gallery once (right-click the desktop → Edit Widgets…) and try again.
To check that it works: turn the cup on and run pmset -g assertions | grep -i coffee.
You should see two "Coffee Control: keep this Mac awake" lines.
Uninstall: open coffeecontrol://quit, delete CoffeeControl.app, and remove
~/Library/Application Support/coffee-control.
Control Center ──tap──▶ CoffeeControlExtension.appex (sandboxed, WidgetKit)
ToggleCoffeeIntent.perform()
└─ open coffeecontrol://on|off ──▶ CoffeeControl.app (windowless agent)
IOPMAssertion ×2
writes state.json
◀── waits until state.json says on/off
CoffeeControl.appis an agent (LSUIElement, no window, no Dock icon). While the button is on, it holds the same two power assertions ascaffeinate -d -i:PreventUserIdleDisplaySleepandPreventUserIdleSystemSleep. If it is not running, a tap launches it, so no login item is needed.CoffeeControlExtension.appexis a sandboxed WidgetKit extension with aControlWidgetToggle. It reads the state from~/Library/Application Support/coffee-control/state.jsonthrough a read-only sandbox exception. There is no App Group, because App Groups do not work with ad-hoc signing. "On" also requires the recorded app process to still be alive.
The usual approach is openAppWhenRun = true: the system launches the app and runs the
intent in its process. With ad-hoc signing (no team ID) this does not work, because linkd
rejects the app process:
linkd: Unable to get teamId from local.coffeecontrol.CoffeeControl
linkd: Rejecting invalid client due to requiresValidatedBundle … com.apple.linkd.mediator
chronod: Failed to execute LNAction … "AppleEvents communication failed."
The toggle then flips for a second and snaps back. So the intent runs in the extension
(openAppWhenRun = false), which forwards the request to the app through the
coffeecontrol:// URL scheme. With a team-signed build (an Apple Development
certificate) you could go back to openAppWhenRun, but there is no need to.
The assertions belong to the CoffeeControl process only. They are released when the
button is turned off or the app exits, including on kill. Other processes, such as a
caffeinate -d -i in a terminal, are neither seen nor touched. The Mac stays awake as
long as any assertion is held.
Needs the macOS 26 SDK. The Command Line Tools for Xcode 26.x are enough; full Xcode is not required:
softwareupdate --list # "Command Line Tools for Xcode 26.x"
./build.sh install # build, ad-hoc sign, install ~/Applications/CoffeeControl.appThen: Control Center → Edit Controls → search "Coffee" → drag the button in. If the search finds nothing, open the widget gallery once (right-click the desktop → Edit Widgets…).
What build.sh does:
swiftcbuilds the app and the extension. The extension is linked with-e _NSExtensionMain, as Xcode does; without it WidgetKit never loads the extension.- App Intents metadata. Xcode writes
Metadata.appintentswithappintentsmetadataprocessor, which the Command Line Tools do not ship. When it is missing,Support/gen_appintents_metadata.pybuilds the index from the compiler's.swiftconstvalues. The format is copied from the system's ownDisplayControls.appex(SetDarkModeEnabledIntent). The script supports only what this project needs and fails on anything else. - Ad-hoc signing (
CODESIGN_IDENTITY, default-), extension first, then the app. installcopies the app to~/Applications, unregisters the./buildcopy, registers the extension withpluginkitand stops a running extension process. Otherwise chronod keeps running the old binary.
Other commands: ./build.sh (build only), ./build.sh dist (universal arm64 + x86_64
build zipped into dist/ for a release), ./build.sh clean.
open coffeecontrol://on # also: off, toggle, quit
pmset -g assertions | grep -i coffee
cat ~/Library/Application\ Support/coffee-control/state.json
pluginkit -m -v -i local.coffeecontrol.CoffeeControl.Control
/usr/bin/log show --last 5m --info --style compact \
--predicate 'process == "chronod" OR process == "CoffeeControlExtension" OR subsystem == "local.coffeecontrol.CoffeeControl"'In zsh, log is a shell builtin, so use the full path /usr/bin/log.
The URL scheme also works from Shortcuts: an "Open URL" action with coffeecontrol://toggle.
Sources/Shared/ CoffeeState (state.json, process check), ToggleCoffeeIntent
Sources/App/ AppDelegate (URL commands, signals), PowerKeeper (IOPMAssertion)
Sources/Widget/ CoffeeControl (ControlWidgetToggle), CoffeeRemote (URL → app)
Support/ Info.plists, entitlements, App Intents metadata generator
build.sh build and install