Can I run agents with the monitors off?

Three different sleeps, often confused for one

macOS has separate timers for the display and for the system, and a third path for the lid. You can see the first two on your own Mac right now:

• pmset -g custom prints your current settings, and displaysleep and sleep are two independent lines — separate timers, separate values, one block for Battery Power and one for AC Power. Both are in minutes; 0 means never.

Display sleep turns the panels off. Nothing else changes: your agent keeps running, downloads keep going, the shell command it launched keeps writing output. Nothing about a dark screen stops work.

System (idle) sleep is the one that hurts. macOS suspends the machine, and every process is frozen where it stood — not killed. That's why it looks so confusing afterwards: the process is still there, the terminal still has your prompt, and the last thing the agent printed is from twenty minutes ago. macOS decides this from your idle time — how long since real keyboard or mouse input — and from the sleep assertions running processes hold. CPU load is not part of it: a Mac at 100% CPU still idle-sleeps on schedule, which is why an agent burning a core all night doesn't save itself.

Closing the lid is not a timer. macOS doesn't consult the idle settings there; it just sleeps. This catches people who set every timer to never and still lose runs. The supported way to keep a MacBook running with the lid shut is clamshell mode — on power, with an external display and an external keyboard or mouse connected. Assume otherwise that the lid is a hard stop.

One footnote that explains why some overnight runs survive without anyone arranging it: ttyskeepawake is on by default, and man pmset describes it as preventing idle system sleep while any tty — a terminal or remote login session — is active, where a tty counts as inactive only once its idle time passes the sleep timer. So a CLI agent printing output into Terminal can hold the machine up on its own. It's a nice accident, not something to depend on: a quiet or detached session doesn't count, and it isn't attributed in either command below.

Display-off is what allows system sleep

This is the reason the question is a good instinct rather than a silly one. While your display is on, macOS itself holds a system-sleep assertion. Run this and look for it:

• pmset -g assertions

Near the bottom you get a list of every process currently holding sleep off, by name. On a Mac with the screen on you'll find a line owned by powerd, currently worded PreventUserIdleSystemSleep named: "Powerd - Prevent sleep while display is on". That's the OS saying: the screen is lit, so I won't idle-sleep yet.

So the sequence that eats overnight runs is: display timer fires → screens go dark → that assertion goes away → the system idle timer is now free to fire → the Mac suspends and your agent stops. The monitors going off didn't stop the work. It removed the accident that was protecting it.

Which also explains a mistake worth avoiding. caffeinate -d holds the display awake, and because a lit display blocks idle sleep, it looks like it fixed the problem. It did — by leaving your panels on all night. If your reason for asking was an external monitor you'd rather not leave burning for eight hours, -d is the wrong flag.

That same list is how you audit any keep-awake tool, including ours: anything holding a power assertion — caffeinate, Amphetamine, KeepingYouAwake, AgentBarista — shows up there by name. One exception worth knowing: pmset -a disablesleep 1 keeps a Mac awake without creating any assertion, so a tool relying on that alone appears nowhere in that list. You catch it with plain pmset -g, which reports it as SleepDisabled 1. AgentBarista runs that command too, in its opt-in lid-closed mode — but on top of a caffeinate assertion, not instead of one, so we're in the assertions list either way. Between the two commands you can see anything holding a power assertion or a disabled sleep timer.

Everything here ships with macOS:

• Hold system sleep only. caffeinate -i your-agent-command blocks idle system sleep for as long as that command runs, and leaves the display timer alone — so your screens still go dark on their own schedule. That is exactly the combination you asked for. It releases itself when the command exits.
• Already running? caffeinate -i -w <pid> attaches to a process that's already going and lets go when it ends. Find the pid with pgrep -l claude, pgrep -l codex, or whatever your agent's binary is called. If several come back, pgrep -x claude matches the process name exactly and skips helper processes — don't reach for -f, which prints full command lines and buries the one you want under pages of flags.
• Turn the screens off now, deliberately. pmset displaysleepnow puts the displays to sleep immediately without touching the system. The keyboard shortcut is Control-Shift-Power (Control-Shift-Eject on older keyboards). Don't confuse it with pmset sleepnow, which is full system sleep and will freeze your agent.
• The permanent setting, if the Mac lives on a desk. System Settings → Displays has a "prevent automatic sleeping when the display is off" option on Macs that qualify — note it applies on the power adapter, not on battery. The exact wording and placement move between macOS versions and models, so confirm the result rather than the label: pmset -g custom will show you the sleep value it actually set, under AC Power.
• Afterwards, settle the argument. pmset -g log | grep -i "Entering Sleep" gives you timestamped sleep events — but read the reason in quotes before you blame it. 'Maintenance Sleep', 'Sleep Service Back to Sleep' and 'Notification Wake Back to Sleep' are short dark wakes that fire many times a night on a healthy Mac — on the Mac this page was written on they were 486 of 624 entries — and they are not your culprit. 'Clamshell Sleep' means the lid closed. 'Software Sleep pid=…' means a program, or you via the Apple menu, asked for it. Any other reason in the window where your agent went quiet is your real sleep event. No entry in that window? Look at a crash, a rate limit, or the agent finishing and waiting on input.

For occasional runs this is genuinely all you need, and there are free menu-bar apps if you'd rather click than type. Amphetamine gets closer than a bare command — its app and CPU triggers do release on their own — but it triggers on a process existing or a CPU threshold, not on an agent's turn ending, so an agent waiting on a model at near-zero CPU can read as finished. With bare caffeinate you hold and release by hand, and forgetting on battery is how people come back to a flat Mac.