coffee-bar

Your Mac stays awake while a coding agent is working, and sleeps the moment the agent is waiting on you.

v0.3.1 · Apple silicon · 1059 KB · macOS 14 or later

The policy bench

Move the controls and watch the decision change. The rows behind this bench are the shipped policy, embedded as data — the page holds no second copy of the rules it is describing.

caffeinate

coffee-bar

The filled bar holds the machine awake. The faded bar lets it sleep. An illustration of when the assertion is held — not a measurement.

Serving is on Auto, the display setting is Sleeps, the Mac is on AC power, and an agent is working.

macOS holds PreventUserIdleSystemSleep.

The screen still sleeps. coffee-bar takes no display assertion unless you ask for one.

The battery floor is a limit on the machine, not on one control position: on battery at or below 15%, coffee-bar releases the hold even when Serving is on On. Off is absolute in the other direction and outranks every session. The bench models the floor where it ships; the Preferences window has a control that moves it, and the Docs page defines it.

The full decision table

The full decision table. Every combination of the four inputs, and what coffee-bar does with it. These 24 rows are the data the bench reads.
Serving	Display	On battery at or below 15%	An agent is working	Holds the system awake	Holds the display awake	Held back by the battery floor
Off	Sleeps	No	No	No	No	No
Off	Sleeps	No	Yes	No	No	No
Off	Sleeps	Yes	No	No	No	No
Off	Sleeps	Yes	Yes	No	No	No
Off	Stays on	No	No	No	No	No
Off	Stays on	No	Yes	No	No	No
Off	Stays on	Yes	No	No	No	No
Off	Stays on	Yes	Yes	No	No	No
Auto	Sleeps	No	No	No	No	No
Auto	Sleeps	No	Yes	Yes	No	No
Auto	Sleeps	Yes	No	No	No	No
Auto	Sleeps	Yes	Yes	No	No	Yes
Auto	Stays on	No	No	No	No	No
Auto	Stays on	No	Yes	Yes	Yes	No
Auto	Stays on	Yes	No	No	No	No
Auto	Stays on	Yes	Yes	No	No	Yes
On	Sleeps	No	No	Yes	No	No
On	Sleeps	No	Yes	Yes	No	No
On	Sleeps	Yes	No	No	No	Yes
On	Sleeps	Yes	Yes	No	No	Yes
On	Stays on	No	No	Yes	Yes	No
On	Stays on	No	Yes	Yes	Yes	No
On	Stays on	Yes	No	No	No	Yes
On	Stays on	Yes	Yes	No	No	Yes

What you see in the menu bar

Two glyphs, and the cup tells you which one at a glance. It reports whether an assertion is held right now — not what your agents are doing, which is what the panel is for. These are the real glyphs, and they are monochrome on purpose: macOS tints template images to match your menu bar, so they stay legible on any wallpaper and in either appearance.

idle Nothing is holding your Mac awake. It is free to sleep.

serving The wake assertion is held. Your Mac stays awake.

What it actually does

Under Auto, holds PreventUserIdleSystemSleep, bound to live agent session state.
Holds no display assertion by default. The screen still sleeps while the work continues. A Display control in the Preferences window opts in when you do want the screen kept on.
Under Auto, releases when every agent is blocked on input, not when a timer expires.
Shows how many sessions are working, and which ones are waiting on you.
Retires a session whose agent crashed, so a dead process cannot pin the machine awake for ever.
Three positions — Off, Auto, On. Off is an absolute veto and outranks everything.
A battery floor, which ships at 15%: on battery, at or below 15%, it does not hold. The Preferences window lets you move it.

The app needs no root for its everyday work. No password prompt, ever. No kernel flags. No App Store. One outbound request, and it is a version check: at most once a day, when it starts, and whenever you press Check now, coffee-bar asks this site which release is current, carrying no identifier and downloading no update. Everything else stays on the machine. The listener that agents post hook events to is a unix socket in a directory only your account can read. The app process never elevates its own privilege: it holds one unprivileged assertion, takes no credentials, and runs no interpreter as root.

Lid-closed mode is the one opt-in extra, and the only part of coffee-bar that involves root at all. Closing the lid sleeps a Mac whatever an assertion says, so holding it open means changing a system setting. coffee-bar asks macOS to install a small helper for that, and macOS runs the helper, not coffee-bar — only once you have approved it yourself under System Settings › General › Login Items & Extensions. There is no prompt to dismiss and still no password. The Preferences window removes it again when you are done, ending the hold before it unregisters. How lid-closed mode works.

Install coffee-bar — the download, the Homebrew tap, and the five Claude Code hooks that tell the app what your sessions are doing. Until those hooks are wired the app runs but no event reaches it.

Read the docs — what each control does, what the panel reports, what coffee-bar reads and what it deliberately does not read.

The policy bench

What you see in the menu bar

What it actually does

Next