caffeinate2

caffeinate but it's written in Rust and has more options. Keeps your Mac wide awake.

Current Status

Almost ready for 1.0.0.

Installation

GitHub Releases

Download the latest release binary from the releases page.

Homebrew

This won't be available until version 1.0.0.

Cargo

CLI only (default):

cargo install caffeinate2

Menu bar + privileged helper:

cargo install caffeinate2 --features full

From a clone:

cargo build --release --features full

The pieces are separate features when you want only one: --features tray builds the menu bar (caffeinate2-tray) and --features helper-bin builds the entirely-mode helper daemon (caffeinate2-helper); full is both.

Either cargo install also installs sleepdetect (a clone build produces it in target/release) — a small diagnostic that logs when the system actually slept, by watching for jumps in a monotonic clock. It takes no arguments; stop it with Ctrl+C.

Usage

Usage: caffeinate2 [OPTIONS] [COMMAND]...

Arguments:
  [COMMAND]...  Trailing command to run (takes priority over `--timeout` and `--waitfor`). End
                options with `--` when the command could be parsed as flags or arguments, e.g.
                `caffeinate2 -t 3600 -- hour`

Options:
      --install-helper      Install the privileged helper for entirely mode (prompts for
                            administrator authorization; or run with sudo). Cannot be combined with
                            other options
      --uninstall-helper    Remove the privileged helper (requires root). Cannot be combined with
                            other options
      --status              Show entirely-mode helper status (holders and sleep state). Cannot be
                            combined with other options
  -v, --verbose             Verbose mode
      --dry-run             Dry run. Don't actually prevent sleep. Useful for testing
      --drop-root           Drop root privileges in command. You need root to disable sleep
                            entirely, but some programs don't want to run as root. Also sets HOME,
                            USER, LOGNAME, and SHELL to the target user's
      --shell               Run COMMAND through /bin/sh -c instead of executing it directly
  -d, --display             Disable display sleep
  -m, --disk                Disable disk idle sleep
  -i, --system              Disable idle system sleep. [DEFAULT]
  -s, --system-on-ac        Disable system sleep while not on battery
  -e, --entirely            Disable system sleep entirely (ignores lid closing)
  -u, --user-active         Declare the user is active. If the display is off, this option turns it
                            on and prevents it from going into idle sleep
  -t, --timeout <DURATION>  Duration to wait before timing out (`-t` / `--timeout`). Takes a single
                            value: bare numbers are seconds; quote human-readable durations (e.g.
                            `"1 hour and 30 minutes"`). Use `--` before a trailing command when it
                            could be confused with flags (e.g. `caffeinate2 -t 3600 -- hour`)
  -w, --waitfor <PID>       Wait for program with PID X to complete and pass its exit code (another
                            user's process can be waited on, but its exit code is unreadable;
                            caffeinate2 then exits 0)
  -h, --help                Print help
  -V, --version             Print version

Sleep Timers (in order of priority)

Command

Sleep is disabled until the command completes. Timeout and PID are ignored when a trailing command is present.

By default the command is executed directly, so arguments keep their boundaries (a filename with spaces stays one argument). Use --shell when you want shell features such as pipes, globbing, or &&.

Put -- before the command when it could be parsed as another option or argument:

caffeinate2 sleep 5

caffeinate2 --shell 'sleep 5 && echo done'

caffeinate2 -t 3600 -- ./script.sh --verbose

caffeinate2 -t 3600 -- hour

Timeout and PID

Sleep is disabled for a certain amount of time, or until the program with the specified PID completes. If both are specified, it waits until one of them completes. The -t countdown follows the wall clock: sleep prevention ends at the promised resume time even if the Mac slept in between (for example the lid was closed, which the default modes don't prevent) — a Mac still asleep at that time ends the session within a minute of waking. Combined with -w, the timeout instead counts awake time toward the PID wait.

-t / --timeout takes one argument:

• Bare number → seconds (e.g. -t 3600)
• Single humantime token → parsed duration (e.g. -t 10m, -t 1.5h)
• Quoted multi-word string → parsed duration (e.g. -t "1 hour and 30 minutes")

The value must be a positive duration — -t 0 (or anything that doesn't parse) is rejected in every mode, including alongside -w or a trailing command.

Supported units include seconds, minutes, hours, days, weeks, months, and years, plus short forms like s, m, h, and d. Anything after the timeout value is treated as a trailing command, not part of the duration — there is no multi-word duration inference, so quote the duration instead:

# Correct: 90 minutes
caffeinate2 -t "1 hour and 30 minutes"

# Wrong: rejected — the trailing words look like a misquoted duration
caffeinate2 -t 1 hour and 30 minutes

For PIDs, caffeinate2 waits until the specified program exits, then exits with the same exit code. If the program doesn't exist, it exits immediately with an error. Another user's process can be waited on, but macOS won't reveal its exit code — caffeinate2 says so and exits 0.

caffeinate2 -t 600

caffeinate2 -t 10m

caffeinate2 -w 1234

caffeinate2 -t 600 -w 1234

None of the above

Sleep will be disabled indefinitely until you press Ctrl+C.

caffeinate2

Menu bar

Run caffeinate2-tray after installing with --features full. To run it in the background instead of occupying the terminal, use -d / --detach:

caffeinate2-tray -d

This returns control to the shell immediately and keeps the menu bar icon running after the terminal closes. Its stderr is captured, best-effort, to ~/Library/Logs/caffeinate2-tray.log (appended, never rotated), and is discarded only if that file cannot be opened; run it in the foreground to watch the logs live. Stop it with the tray's Quit item or pkill -x caffeinate2-tray.

• Left click: toggle the selected sleep modes on/off — or, while caffeinate2 is upgrading another app's sleep assertion, open the upgrade dialog (see below).
• Right-click: open the menu:
  • Mode — Display, Disk, System, System (on AC), User active, Entirely. These are independent checkboxes, not a single choice: pick as many as you need and one session holds all of them. Entirely plus User active is the useful pair for agents — Entirely keeps the Mac awake with the lid shut, User active also keeps the screen from locking so the agent can drive the UI. At least one mode stays selected; clicking the last checked one does nothing.
  • Time limit — Off, 15 minutes, 30 minutes, 1 hour, and so on.
  • Wait for apps… — pick one or more running apps, or use the Choose application picker (button Choose) for any .app.
  • Upgrade other apps' sleep prevention — see below.
  • Ignored apps — the programs that are never upgraded; click one to stop ignoring it (shown only when the list is non-empty and the upgrade watcher is on — with the watcher off the list governs nothing, but it stays in tray.toml and reappears when the watcher is re-enabled).
  • Start at login — toggle the LaunchAgent.
  • Quit.

When a time limit is set, left-clicking to start sleep prevention turns it off again after that duration (like caffeinate2 -t). Changing the selection while sleep prevention is running re-acquires every selected mode, keeping the old holds until the new ones are in place; if any of them fails, the whole change is rolled back and the previous holds stay. Wait for apps keeps prevention on until every instance of all the selected apps has exited (it stops once at least one selection has been seen running and then none remain); any selected app that isn't running yet is waited on to launch. With both set, whichever comes first wins. While a time limit is counting down, the minutes remaining (rounded up, e.g. 29m or 1h 29m) are shown next to the menu bar icon; the tooltip shows remaining time and/or app status while active. Time limits follow the wall clock: a 1-hour limit ends an hour after it started even if the Mac slept mid-session (for example the lid was closed, which every mode except Entirely allows) — asleep time counts.

Upgrade other apps' sleep prevention keeps the Mac awake on behalf of tools that can't. Tools like Claude Code, Codex, and caffeinate -i use a low-level assertion that still allows sleep when the lid closes — so a long-running agent dies the moment you shut the lid. With this on, caffeinate2 watches for those assertions and temporarily upgrades to Entirely mode while one is active.

• Requires the privileged helper. Enabling the toggle installs it if necessary (prompting once).
• Only your programs are upgraded. macOS's own processes hold sleep assertions during ordinary use all the time (the power daemon, runningboardd, audio and media daemons, Apple's apps); they release them on their own, so caffeinate2 ignores every one of them and never mentions them in the menu.
• The menu shows which app triggered the upgrade, and lists assertions it deliberately ignores.
• While an upgrade is active, left-clicking the icon opens the upgrade dialog (below) rather than simply switching sleep prevention off — "off" would be ambiguous when the hold is being taken on another program's behalf. It still toggles off directly in the one case the dialog has nothing to ask about: an upgrade whose holder exposes no process name.
• A manual left-click-off — when the watcher is idle, or from that nameless-holder case — overrides the watcher until the next new assertion.

The upgrade dialog. Left-clicking the icon while an upgrade is active asks what to do with it instead of just switching it off (with several apps upgraded at once, a pop-up in the dialog picks which one the ignore choices apply to):

• Hold For 30m (or Hold Until I Stop It with no time limit set) — take over with caffeinate2's own session, using the configured modes and time limit. Useful when you don't know how long the other app will keep asserting but you do know how long you need the Mac awake. The watcher stays out of the way until that app's assertion goes away.
• Ignore This Time — stop upgrading the assertion it is holding right now. The ignore expires once that app has stopped asserting for about 5 seconds, so the next thing it starts is upgraded again.
• Never Upgrade This App — add it to the ignore list under Ignored apps, where clicking it removes it again.
• Cancel — leave the upgrade running.

Settings are stored in ~/Library/Application Support/caffeinate2/tray.toml. The selected modes live there as modes = ["user_active", "entirely"]; a file written by an older version, which stored a single mode, is read and migrated on the next save.

Start at login writes ~/Library/LaunchAgents/com.randomblock1.caffeinate2-tray.plist and takes effect at the next login (the tray does not start a second instance immediately). Use -d for a one-off background launch right now; use the LaunchAgent to start the tray at every login. The menu toggle and these CLI flags use the same LaunchAgent:

caffeinate2-tray --install-launch-agent

caffeinate2-tray --uninstall-launch-agent

caffeinate2-tray --launch-agent-status

Unsigned binaries may require running from Terminal once (right-click → Open) or allowing in Privacy & Security.

Details

• Time limit countdown: changing the time limit while sleep prevention is active restarts the countdown from that moment — it is not measured from when the session started.
• Wait for apps matching: the target is remembered by bundle ID (for example Codex.app stays matched across restarts).
• Upgrade release delay: caffeinate2 releases its Entirely hold about 5 seconds after the external assertion goes away — long enough to ride out the gaps agents leave between turns, short enough that a Mac whose agent has really finished is free to sleep almost at once. Through those seconds the menu says so — Claude stopped asserting — releasing hold — rather than continuing to name the app as though it were still keeping the Mac awake; the tooltip counts down the remaining time, and clicking the icon offers to release the hold now instead of waiting it out.
• Upgrade menu display: a single named app appears as one line; several collapse into an expandable Upgrading N apps submenu (the tooltip lists them too). When an app's name is unavailable, a generic Upgrading external app line is shown instead.
• Ignored assertions: caffeinate2 only reacts to idle-system-sleep assertions (what agents use). Others are listed under Ignoring name (reason) lines — collapsing into an Ignoring N assertions submenu when there are several — so a quiet menu is never mistaken for "nothing is keeping the Mac awake." The reason is display only for the display-only assertions video players hold, you ignore this app for the persistent ignore list, and ignored this time for a one-off ignore. caffeinate2 never reacts to its own holds.
• What counts as a system program: anything running as another user (root daemons and service accounts like coreaudiod), any Apple .app, anything launched from /System, /usr/libexec, /usr/sbin, /sbin or /Library/Apple — macOS's daemons and per-user agents — and any process whose executable can't be read. These are silently dropped: never upgraded, never listed. Everything else you run is upgradeable, including Homebrew binaries and Apple's own command-line tools: caffeinate -i from /usr/bin is you asking to stay awake, not the OS doing housekeeping.
• Ignored apps list: stored as ignored_apps in tray.toml (a list of process names as IOKit reports them, matched case-insensitively) and editable by hand as well as from the menu. Ignoring an app takes effect immediately: if nothing else is worth upgrading, the hold is released right away rather than after the usual 5-second delay.
• Any matching assertion counts: a desktop app that holds an idle-system-sleep assertion while open (some Electron apps do) will keep the upgrade active until it quits.

Entirely mode

Entirely mode (-e / tray Entirely) disables system sleep even when the lid is closed. It uses a small privileged helper daemon, so once installed it works without repeated password prompts.

One-time setup (either method):

1. Tray: select Entirely and approve the administrator dialog when prompted, or
2. CLI: sudo caffeinate2 --install-helper

Helper install requires caffeinate2-helper next to caffeinate2: use cargo install caffeinate2 --features full, build with --features full, or extract the GitHub release bundle (all three binaries together).

After that, caffeinate2 -e and tray Entirely use the helper without further passwords.

Who can use it: root and administrator accounts, plus members of the caffeinate2 group (created by --install-helper). The helper denies everyone else, since disabling sleep entirely is otherwise a root-only setting. To allow a standard account:

sudo dseditgroup -o edit -a USERNAME -t user caffeinate2

The grant takes effect on the user's next attempt (no logout needed). Denied requests show the exact grant command; caffeinate2 --status works for every account.

Other helper commands:

• Remove the helper: sudo caffeinate2 --uninstall-helper (refuses while entirely-mode sessions are still active)
• Check helper state (running, how many holds, sleep disabled, version): caffeinate2 --status

After upgrading caffeinate2, reinstall the helper: the installed daemon is a copied snapshot, so it keeps running the old version until you run sudo caffeinate2 --install-helper again. caffeinate2 --status shows when the installed helper's version differs from the binary (the tray also logs a warning at startup).

The helper logs to the unified system log (subsystem com.randomblock1.caffeinate2.helper); view it with Console.app or log show --predicate 'subsystem == "com.randomblock1.caffeinate2.helper"'.

License

This project is licensed under the MIT License.