Keep your Mac awake while an AI agent runs: Claude Code, Codex, Cursor, Ollama

The scene is always the same. You hand a long task to Claude Code, Codex, a Cursor agent or a local model, see it working, close the lid or walk away, and in the morning the run stopped twenty minutes after you left. The Mac went to sleep. This page explains the two kinds of sleep involved, why the usual trick only beats one of them, and the ways to keep the Mac working for as long as the agent needs.

Two different sleeps

macOS puts a Mac to sleep for two unrelated reasons, and they need different answers.

• Idle sleep. Nothing has touched the keyboard or mouse for a while, so the system assumes nobody needs it. The threshold is in System Settings under Energy or Battery. Any app can hold this off by asking the system for a power assertion. That is what caffeinate, Amphetamine and Valpas do.
• Clamshell sleep. The lid closed. This is a lower-level trigger and it does not care about assertions. macOS keeps a closed MacBook awake only when an external display and the power adapter are connected. Otherwise the lid wins, whatever is running.

A terminal process does not count as activity. An agent can be mid-edit, mid-build or mid-request and the Mac still believes it is idle. So a long run needs something to hold idle sleep off. If you also want to shut the lid, it needs something that handles clamshell sleep as well.

Lid open: the simple case

If the Mac can stay open on a desk, you only need to beat idle sleep. Options, from the most manual to the least:

The caffeinate command. Built into macOS. caffeinate -i keeps the system awake while the command runs. Wrap the agent in it:

caffeinate -i claude

The assertion lives exactly as long as the agent does. The catch is that it dies with the terminal window, and it does nothing for a second agent you start elsewhere.

An agent plugin. Claude Code has hooks that fire on each prompt and tool call, and there are small plugins that restart a short caffeinate timer on each one, so the Mac stays awake while the agent is active and sleeps a few minutes after it goes quiet. Neat for one tool, and it is tied to that tool.

A watched app. Menu bar apps that can watch another app cover every agent at once. In Valpas, set the trigger While an app is running to the terminal or editor the agents live in: Terminal, iTerm, Warp, Ghostty, Cursor, VS Code, or the Ollama menu bar app. While that app is open the Mac stays awake. Quit it and sleep comes back. Pick Allow display to sleep so the screen goes dark and locks on schedule while the Mac keeps working underneath.

A watched process. Since Valpas 1.3 there is a second trigger, While a process is running, that takes names instead of an app: claude, codex, ollama. The Mac stays awake while any of them is alive and is free to sleep when the agent exits, whatever terminal it ran in. Names match both the process and the command it was started with, so claude finds the native binary and the npm script running under node, and ollama serve from a launch agent counts too.

A plugin inside the agent. For Claude Code there is also valpas-keep-awake, a plugin whose hooks ask Valpas for twenty more minutes on every prompt and tool call. When Claude stops, the last hold runs out by itself. Install it with /plugin marketplace add KirsuLab/valpas-keep-awake and /plugin install valpas-keep-awake@valpas-keep-awake.

A timer. If you know the job takes about three hours, hold the Mac awake for four and let it fall asleep on its own afterwards. Valpas does this from the menu bar, or from the terminal in the direct-download build:

valpas 4h

Unlike caffeinate, the session belongs to the app rather than the shell, so closing the window changes nothing, the countdown is visible in the menu bar, and the battery guard still ends it if the charge runs low. Two more commands are made for scripts and agents:

valpas run -- claude      # awake while the command runs, then let go
valpas hold 20m           # awake for at least 20 more minutes, never less

hold never shortens a session you set by hand and never outlives its own length, so a script can repeat it while it works without pinning the Mac awake afterwards. run does exactly that around any command. valpas status returns zero while the Mac is being held.

Lid closed: the hard case

Nothing above survives the lid closing. For that you have three real choices.

An external display and the power adapter. Apple's own clamshell mode. Plug both in, close the lid, and macOS keeps running. A cheap HDMI dummy plug stands in for a monitor if you do not have one. This is the officially supported way and the only one that needs no system change.

pmset disablesleep. A hidden power setting that turns clamshell sleep off entirely:

sudo pmset -a disablesleep 1

Close the lid and the Mac keeps working, no display needed. It works on Apple silicon. The problem is that it is global and permanent until you undo it:

sudo pmset -a disablesleep 0

Forget that second command and the Mac never sleeps again by itself, including unplugged in a bag. That is the single most common way this approach bites people.

An app with a lid-closed mode. The same setting, held only for the length of a session and put back automatically. The direct download of Valpas has one switch for this, Keep running with the lid closed, through a small helper you allow once in System Settings. Start a session, shut the lid, and sleep comes back by itself four ways: when the session ends, when the adapter is unplugged, when Valpas quits or is not running, and when macOS reports serious thermal pressure. The App Store build cannot do this, because its sandbox does not allow the helper, so the lid-closed mode lives in the direct download and the Homebrew cask, signed and notarized with an Apple Developer ID. It is free for seven days from the first hold. After that a Valpas Pro key, $19.99 once for up to three Macs, keeps it.

Which one, in a table

	Idle sleep	Lid closed	Ends by itself	Setup
System Settings, never sleep on adapter	Yes	No	No	Two clicks
caffeinate -i	Yes	No	With the command	None
Agent plugin	Yes	Some, via sudo rule	Minutes after the agent	Install into one agent
Amphetamine	Yes	No	Timer or trigger	Free app
External display or dummy plug	Yes	Yes	No	Hardware
pmset disablesleep by hand	Yes	Yes	No	One command, one to undo
Valpas (ours)	Yes	Direct download, 7 days free, then a key	Timer, battery, app or process trigger, heat	Free, lid key $19.99

We make Valpas, so read that row with that in mind. Amphetamine is a fine free choice for the lid-open case and has more triggers than most people will use. For lid-closed runs the real competition is the dummy plug, which costs a few dollars and needs no software at all. Pro earns its place when you want the lid hold to switch itself off on a timer, on battery and on heat, and the Mac back to normal without remembering a command.

Heat, battery and the morning after

• Heat. A closed MacBook cannot breathe through the keyboard. An agent waiting on an API barely warms the machine. A local model on the GPU does. Hard surface, vents clear, never a bed, cushion or bag.
• Battery. Do not run overnight on battery. Everything here assumes the power adapter, and Valpas refuses the lid hold without it.
• The lock screen. With the display allowed to sleep, the Mac locks as usual. The agent keeps working behind the lock screen. In Pro's Keep display on mode the panel goes to zero brightness instead, so opening the lid does not ask for a password.
• Check it ended. Whatever you use, make sure it has a visible state. A menu bar countdown or valpas status tells you the Mac is held. A forgotten pmset setting tells you nothing.

Short answer

Lid open: wrap the agent in caffeinate -i, or set a menu bar app to watch your terminal. Lid closed: plug in a display or a dummy plug, or use a tool that sets pmset disablesleep for the session and takes it back. Either way, on the adapter and on a hard surface.

Two narrower pages: Run Codex CLI and other terminal agents overnight and Ollama on a MacBook as an always-on model server. For the general case without agents, see Your Mac keeps going to sleep and caffeinate vs Amphetamine vs Valpas.