What happens when you close the lid

The Mac goes to sleep. The agent’s process freezes, its network connection drops, and nothing more happens until you open the lid again. What you see then depends on the agent:

Claude Code notices the sleep. If it was mid-reply, it stops with API Error: Your computer went to sleep mid-response. The response above may be incomplete. (what that means).
Codex CLI can sit stuck “reasoning” until the lid opens (#34358), and requests can fail with error sending request for url after a sleep (#3355).

This catches people out because the agent’s own keep-awake setting is on, and it seems like it should work. It doesn’t, for a reason that has nothing to do with the agent.

Why caffeinate can’t help with the lid shut

macOS has two kinds of sleep. Apple’s QA1340 defines them:

Idle sleep “occurs when the machine is unused for a specific period of time”.
Forced sleep “occurs when the user takes some sort of direct action to cause the machine to sleep. Closing the lid on a laptop or selecting sleep from the Apple menu both cause forced sleep.”

Apps hold off idle sleep with a “power assertion”. That’s what caffeinate -i creates, and it’s what Claude Code’s CLI, Codex’s prevent_idle_sleep and the Claude desktop app’s Keep computer awake rely on. For forced sleep, Apple is blunt: “it is not possible to prevent forced sleep, only delay it.”

What about caffeinate -s? The man page says it prevents “the system from sleeping” and is “valid only when system is running on AC power”. Some guides say that keeps a closed MacBook awake on the charger. Others say it never does. Test it on your own Mac before you trust an overnight run to it.

The free options, honestly

1. Keep the lid open and wrap the agent in caffeinate

This is enough for most people. Leave the lid open (the screen can still turn off and lock), and start the agent through caffeinate:

caffeinate -i claude

caffeinate -i codex

caffeinate holds off idle sleep “as long as that process is running” (man page). The catch: it also holds while the agent sits waiting for you, so quit the agent when you’re done. If the agent is already running, or lives in an editor, hold the Mac for a set time instead (two hours here) or until a process ends:

caffeinate -i -t 7200
caffeinate -i -w 12345

Replace 12345 with the agent’s process ID.

On the charger, also turn on Prevent automatic sleeping on power adapter when the display is off in System Settings › Battery › Options (Apple). On our own Mac, over one week, seven to twelve of the 15 to 23 Claude Code runs cut short by sleep happened on the charger, where that setting would have stopped it.

2. Closed-display mode, with an external display

macOS keeps a closed MacBook running when it drives an external display. For a closed-lid Mac, Apple says to “make sure that the Mac is connected to power and using an external keyboard and mouse” (Apple). If you have a desk setup, this needs no extra software.

3. Run it in the cloud

If the work doesn’t need your Mac, let someone else’s computer stay awake. Claude Code has cloud sessions, Codex has cloud tasks, and Cursor has Cloud Agents. For a task that must run while your computer is asleep or off, Anthropic’s desktop docs suggest a cloud session.

4. Turn sleep off entirely (careful)

There’s a system switch that turns sleep off for the whole Mac:

sudo pmset -a disablesleep 1

Apple’s note on it: “When the value is set to 1, all sleep functions are disabled” (Apple). It stays on until you turn it back off, whether or not the agent has finished:

sudo pmset -a disablesleep 0

Forget that second line and your Mac won’t sleep, on the charger or on battery, or in a bag. This is the switch that lid-mode apps flip for you. The difference is that they also flip it back.

Lid mode: when you want to close the lid and walk away

A lid mode tool turns that switch on only while your agent works, and back off when it’s done, or when something goes wrong. Several apps do this; /compare lists them with their prices and guards.

Night Crew’s lid mode works like this:

Only while an agent works. Normal sleep comes back as soon as the agent finishes.
Charger only, by default. You can allow battery, and then it stops at 30%.
One helper, approved once. You approve a small helper in System Settings. It can only turn sleep off and back on, and it turns sleep back on if Night Crew quits.
Heat guard, always on in lid mode. If the Mac gets warm, Night Crew lets it sleep.

Before you close the lid

Plug in if you can. Lid closed or not, the agent’s work still drains the battery.
Hard surface, never a bag. Apple asks for “a stable work surface that allows for good ventilation” and an ambient temperature between 10 and 35 °C (Apple). A bag traps heat quickly.
Approvals. If the agent stops to ask your permission, it waits with the lid shut too. Allow what it needs before you leave.
Check afterwards. pmset -g log shows every sleep and its cause, so you can see if the Mac slept anyway.

For the per-agent detail, see Claude Code, Codex and Cursor, or Does Claude Code prevent sleep?

Can I close my MacBook while Claude Code or Codex is running?