GitHub - ObservedObserver/Macchiato: Keep your Mac awake while your code agent works — even with screen off, lid closed

3 min read Original article ↗

Macchiato logo

A tiny macOS menu bar utility that keeps your Mac awake with one button.

What It Solves

Mac-chiato is built for people who leave long-running work on their Mac: coding agents, local automation, builds, data jobs, model runs, downloads, and anything else that should keep going while you step away.

screenshot

When you need to close your computer, you should be able to close it normally. No leaving the lid slightly open, no changing system settings by hand, and no wondering whether the agent that was halfway through a task got interrupted.

Macchiato gives you a single menu bar switch:

  • On: keep the Mac awake, including lid-closed use.
  • Off: restore normal macOS sleep behavior.

How To Use

  1. Launch Macchiato.
  2. Click the menu bar icon.
  3. Turn on Keep Awake before starting or leaving a long-running task.
  4. Close the lid whenever you need to move, pause, or put the Mac aside.
  5. Turn Keep Awake off when you want macOS to sleep normally again.

The first time Macchiato enables lid-closed sleep control, macOS may ask you to approve Macchiato Helper in System Settings. After that approval, the regular on/off switch should work without asking for administrator credentials every time.

Good For

  • Agents that continue working while you are away from the keyboard.
  • Local development servers, builds, test runs, and scripts.
  • Long downloads, syncs, exports, or processing jobs.
  • Any moment where you want to close the MacBook without babysitting the lid.

For long sessions, keep an eye on battery and heat, especially if the Mac is closed and not plugged in.

If Something Goes Wrong

If Macchiato is force-quit or crashes while enabled, you can manually restore normal sleep behavior:

sudo pmset -a disablesleep 0

Development

Macchiato uses an IOKit PreventUserIdleSystemSleep assertion plus macOS' pmset disablesleep setting. The app ships a privileged LaunchDaemon helper, installed through SMAppService, so the system-level pmset work is approved once instead of prompting on every toggle.

Internal distribution uses the project's private signing flow. Release builds must not include debug signing entitlements such as get-task-allow, and the app and embedded helper must be signed consistently before packaging the DMG. Users approve/trust the internal build through macOS, then Macchiato registers the helper through SMAppService.

Build locally:

xcodebuild -project Macchiato.xcodeproj -scheme Macchiato -configuration Debug build

Build the internal distribution DMG:

Additional xcodebuild build settings can be passed through when needed by the internal signing flow.

The Macchiato target depends on Macchiato Power Helper and embeds the helper executable plus its launchd plist into:

Macchiato.app/Contents/MacOS/app.macchiato.Macchiato.PowerHelper
Macchiato.app/Contents/Library/LaunchDaemons/app.macchiato.Macchiato.PowerHelper.plist

Verify The Assertion

Launch the app, turn on Keep Awake, then run:

pmset -g assertions | grep Macchiato

You should see a PreventUserIdleSystemSleep assertion named Macchiato is keeping your Mac awake.

You can also verify the lid-closed sleep setting:

pmset -g live | grep SleepDisabled

Local Sleep Logging Test

The repo includes two local scripts for manual acceptance testing:

scripts/sleep-log-runner.sh --scenario lid-closed-off
scripts/sleep-log-runner.sh --scenario keep-awake-on
scripts/analyze-sleep-log.sh sleep-test-logs/*.csv

Suggested flow:

  1. Ensure Macchiato is off, start scripts/sleep-log-runner.sh --scenario lid-closed-off, close the lid or otherwise trigger the sleep condition, wait 10 minutes, reopen the Mac, then stop the logger with Ctrl+C.
  2. Turn on Keep Awake, start scripts/sleep-log-runner.sh --scenario keep-awake-on, repeat the 10 minute window, reopen the Mac, then stop the logger.
  3. Run scripts/analyze-sleep-log.sh sleep-test-logs/*.csv.

The analyzer reports sample count, wall time, maximum timestamp gap, whether the Macchiato power assertion was observed, and how many samples saw SleepDisabled=1. A large gap means the logger stopped running during the test window, which usually indicates sleep.