Skip to content
Agent CaffeineDownload
Blog

The caffeinate command on Mac, explained (with tests)

· Updated · By Mert Duzgun

caffeinate is a command built into macOS that keeps your Mac awake. Type caffeinate in Terminal and the Mac does not idle sleep until you press Ctrl+C; type caffeinate -i followed by a command, such as caffeinate -i make, and it stays awake until that command ends. It does not keep a MacBook awake with the lid closed on battery.

There is nothing to install. It lives at /usr/bin/caffeinate on every Mac. We ran every flag below on macOS 26.7.1 on October 29, 2026, and checked what each one does with pmset -g assertions. One result does not match the manual, and we say where.

How caffeinate works

The manual describes it in one line: "prevent the system from sleeping on behalf of a utility". It does this with power assertions. An assertion is a request to macOS that says "do not sleep now". When caffeinate exits, its assertions go away and your normal sleep settings apply again.

You use it in one of two ways:

  • On its own. It holds the assertion until you press Ctrl+C, a timeout ends, or a process you told it to watch ends.
  • In front of a command. It runs the command and holds the assertion while the command runs.

With no flags it prevents idle sleep, the same as -i.

Every flag, and the assertion it makes

Flag What it prevents Assertion in pmset -g assertions Note
-d Display sleep PreventUserIdleDisplaySleep Keeps the screen on
-i Idle system sleep PreventUserIdleSystemSleep The default; right for most jobs
-m Disk idle sleep PreventDiskIdle Rarely needed on SSD Macs
-s System sleep PreventSystemSleep Only on AC power
-u Declares the user active UserIsActive Turns the display on; 5 seconds without -t
-t N Ends after N seconds (none) See the note below
-w PID Ends when that process exits (none) Ignored with a wrapped command

We read the assertion names from pmset -g assertions while each flag ran. Flags stack, so caffeinate -d -i keeps both the screen and the Mac awake.

-i: prevent idle sleep

caffeinate -i

The Mac keeps running, but the display still turns off on its normal timer. Downloads, builds and scripts continue.

-d: keep the display on

caffeinate -d

For a presentation, a dashboard, or a video player that does not keep the screen on by itself.

-s: prevent system sleep, on power only

caffeinate -s

The manual: "This assertion is valid only when system is running on AC power." On power, this is the one flag that keeps a MacBook running with the lid closed. On battery it does nothing.

-u: declare that the user is active

caffeinate -u -t 600

If the display is off, -u turns it on and keeps it from idle sleep. Without -t it lasts only 5 seconds, so pair it with a timeout.

-m: prevent disk idle sleep

caffeinate -m

Stops disks from spinning down. On a Mac with only an SSD you will rarely need it.

-t: stop after a number of seconds

caffeinate -i -t 3600

The time is in seconds, not minutes: 1800 is 30 minutes, 3600 is one hour, 7200 is two hours, 28800 is eight hours.

The manual is wrong here, at least on macOS 26. It says the timeout "is not used when an utility is invoked". In our test, caffeinate -i -t 2 sleep 5 dropped its assertion after 2 seconds while sleep was still running. So do not add -t to a wrapped command unless you want the Mac free to sleep before the command ends.

-w: wait for a process to exit

caffeinate -i -w 12345

Holds the assertion until process 12345 exits. Use it when a long job is already running and you forgot caffeinate. Find the process ID with pgrep:

caffeinate -i -w "$(pgrep -n -x rsync)"

Wrap a command

The manual's own example is the most useful form:

caffeinate -i make

caffeinate starts make and holds the assertion while it runs. A few more:

caffeinate -i ./backup.sh
caffeinate -i npm run build
caffeinate -i rsync -a ~/Photos /Volumes/Backup

The exit code of your command comes through. caffeinate -i sh -c 'exit 7' ended with 7 in our test, so a script that checks the result works as before.

Run it in the background

To keep your terminal free, add &:

caffeinate -i -t 7200 &

Stop it later with kill %1 in the same window or killall caffeinate from any window. A caffeinate that you start in a window ends when you close that window, so for a long run, start it inside tmux or a terminal tab you keep open.

To keep the Mac awake for exactly as long as your current shell is open:

caffeinate -i -w $$ &

$$ is the process ID of the shell, so the assertion ends when you close it.

Check that it works: pmset -g assertions

pmset -g assertions

Under "Listed by owning process" a running caffeinate looks like this (from our Mac):

pid 82403(caffeinate): [...] PreventUserIdleSystemSleep named: "caffeinate command-line tool"
	Details: caffeinate asserting for 3 secs

For a wrapped command, the details line says asserting on behalf of 'make' (pid ...). If you see more caffeinate lines than you started, another program started them. On our Mac those came from Claude Code (see below).

What caffeinate cannot do

A closed lid on battery. Closing a MacBook's lid is its own kind of sleep. Only -s holds it, and only on power. On battery you have two ways out, both outside caffeinate:

  1. Closed-display mode. Apple's requirement: "If the display is connected to a Mac laptop computer with a closed lid, make sure that the Mac is connected to power and using an external keyboard and mouse."
  2. sudo pmset -a disablesleep 1. Turns sleep off completely, lid closed included. It is not in the pmset manual, so treat it as undocumented, and turn it off with sudo pmset -a disablesleep 0 when you are done.

Our guide on how to keep a Mac awake with the lid closed covers both with a test.

Common reasons it "does not work":

  • The screen went dark: you used -i without -d. The Mac is still awake.
  • The timeout ran out: -t 60 is one minute, not one hour.
  • You used -s on battery.
  • You closed the terminal window that ran it.
  • You used -u without -t, so it lasted 5 seconds.

caffeinate and AI coding agents

Coding agents such as Claude Code, Codex and opencode can work for an hour without input. If the Mac sleeps, the agent stops halfway.

What Claude Code already does. On our Mac, Claude Code sessions (version 2.1.312) started a child process caffeinate -i -t 300 and started a new one as each ran out, so they block idle sleep five minutes at a time. Not every open session had one, and we did not pin down exactly when Claude Code starts and stops it, so do not count on it for a long unattended run. It is still -i, so a closed lid on battery sleeps. We did not see this in other agents; check yours with pmset -g assertions.

Wrap the agent yourself:

caffeinate -i codex

The Mac stays awake while the session is open, also while the agent sits idle at its prompt waiting for you. To also hold a closed lid on power:

caffeinate -is claude

Attach to an agent that is already running:

caffeinate -i -w "$(pgrep -n -x codex)"

If this finds nothing, run pgrep -l codex to see the process name on your install, and use that name instead.

Run it under tmux for overnight work, so closing a terminal window does not end it:

tmux new-session -d -s agent 'caffeinate -i claude'

These work. They have two gaps: you have to remember to start them, and none of them holds a closed lid on battery.

Where Agent Caffeine helps

We built Agent Caffeine for that gap. It is a menu bar app that keeps the Mac awake while coding agents work and lets it sleep when they are done.

  • It finds more than 40 agents, and reads from Claude Code and Codex whether they work, wait for you or are idle, so an idle agent does not hold the Mac awake.
  • A closed lid works on power from the start, and on battery with a small helper you allow once.
  • It lets the Mac sleep at a low battery or when the Mac gets too hot.
  • Scripts can ask for the same thing with agent-caffeine hold -- <command>, see keep your Mac awake while a command runs.

It has a trial and needs macOS 13 or later. If caffeinate in a tab does the job for you, keep using it.

Questions

How do I use caffeinate on a Mac?

Open Terminal and type caffeinate. The Mac will not idle sleep until you press Ctrl+C. To keep it awake only while a command runs, put caffeinate in front of it, for example caffeinate -i npm run build. To keep it awake for one hour, run caffeinate -i -t 3600.

Does caffeinate work with the lid closed?

Mostly no. -i, -d, -m and -u do not stop the sleep that comes from closing the lid. caffeinate -s keeps a closed MacBook awake, but only on the power adapter. On battery, no caffeinate flag holds a closed lid.

How do I stop caffeinate?

Press Ctrl+C in the Terminal window where it runs. From another window, run killall caffeinate. With -t it stops by itself when the time runs out, and with -w or a wrapped command it stops when that process ends.

How do I know if caffeinate is running?

Run pmset -g assertions and look under "Listed by owning process" for a line with caffeinate and the name "caffeinate command-line tool". It also shows the type of assertion, such as PreventUserIdleSystemSleep, and how many seconds are left on a timeout.

Does Claude Code keep my Mac awake by itself?

In our test with Claude Code 2.1.312 on macOS 26, Claude Code sessions ran caffeinate -i -t 300 and renewed it, which blocks idle sleep five minutes at a time. That covers an open lid. It does not keep a closed MacBook awake.

Sources

  • man caffeinate (caffeinate(8), macOS) and man pmset (pmset(1), macOS)
  • Our tests on macOS 26.7.1 (build 25G241), October 29, 2026: each flag with pmset -g assertions, -t with a wrapped command, exit codes, and the Claude Code child process
  • Apple Support: If your external display is dark or low resolution (closed-display mode requirements)