Run Codex CLI and other terminal agents overnight on a Mac

arrow_back Valpas

Terminal agents are good at long, boring tasks: a migration across sixty files, a test suite fixed one failure at a time, a refactor with a review pass at the end. The natural move is to start one in the evening and read the result in the morning. The thing that spoils it is the Mac going to sleep an hour after you left. Here is the checklist we use.

1. Know which agents run on your Mac

Not all of them do, and that changes everything.

Runs on your Mac	Runs in the cloud
Codex CLI in a terminal	Codex in the cloud sandbox
Claude Code in a terminal	Claude Code on the web
Gemini CLI, Aider, OpenCode, Goose	Cursor background agents
Cursor agent in the editor	Devin and other hosted agents

The right column keeps running when your Mac sleeps, because the work is not on your Mac. Close the lid and go to bed. Everything below is about the left column.

2. Understand why the Mac sleeps under a working agent

A process is not activity. macOS counts keyboard and mouse input, and after the idle period in System Settings it sleeps the system, agent or not. Sleep suspends every process and every network connection. The agent is waiting on an API call, the call times out, and the run falls over.

Closing the lid is a second, separate sleep that ignores the usual fixes. Section 5 is about that one.

3. Hold the Mac awake for the run

Three ways, from the most manual to the least.

Wrap the agent. caffeinate -i codex or caffeinate -i claude. The Mac stays awake exactly as long as the command runs. It stops working when you close the window and it covers only that one command.

Watch the process. In Valpas, switch on While a process is running and type the names: codex, claude, gemini. The Mac stays awake while any of them is alive and is free to sleep when the last one exits, whichever terminal it ran in. One switch covers every agent, and the build or the download running beside them.

Let the agent ask. The direct-download build of Valpas ships a valpas command. valpas run -- codex holds the Mac while the command runs. valpas hold 20m asks for at least twenty more minutes without ever shortening a session you set by hand, so a script can repeat it while it works and the Mac is free one grace window after it stops. For Claude Code there is a plugin, valpas-keep-awake, that does that from the agent's own hooks.

4. Let the screen sleep and lock

The display and the system sleep separately. Hold the system awake and let the display go dark on its usual schedule, and the Mac locks as it always does. The agent keeps working behind the lock screen, and nobody who walks past sees your code or your terminal.

In Valpas this is Allow display to sleep. With caffeinate, use -i and not -d, which would keep the display lit too.

5. Decide about the lid

Lid open on a desk: you are done after step 3.

Lid closed: caffeinate, Amphetamine and every power assertion stop working the moment it shuts. The choices are an external display with the power adapter, which is Apple's supported clamshell mode and can be faked with a dummy HDMI plug, or the hidden pmset disablesleep setting, by hand or through a tool that puts it back. The direct download of Valpas does the latter for the length of a session and hands sleep back on timer, on battery, on quit and on heat, free for seven days and then with a Pro key. The pmset page has the details and the one regret to avoid.

6. Power and heat

Plug in. Overnight on battery is how agents die at four in the morning with the Mac at two percent. Coding agents are light work and barely warm the machine, but with the lid closed keep it on a hard, open surface anyway.

7. Check in the morning

Have the hold be visible. A countdown in the menu bar, or valpas status, tells you the Mac was held and for how long. For proof, pmset -g log | grep -i sleep lists every sleep and wake with a timestamp. If the log shows a sleep at 1:12 and a wake at 7:40, the agent did not work between them, however good the fix looked at midnight.

The short version

Local agent, lid open: caffeinate -i <agent> or a watched process in a menu bar app, with the display allowed to sleep. Lid closed: a display or a lid-closed mode. Plugged in, hard surface, and a countdown you can see.

Questions & answers

Does my Mac need to stay awake for Cursor background agents?expand_more

No. Cursor's background agents and the cloud modes of Codex and Claude run on remote machines, and your Mac can sleep. It is the local terminal agents, Codex CLI, Claude Code, Gemini CLI, Aider, OpenCode, that stop when the Mac does. This page is about those.

Why does the agent stop when my Mac sleeps?expand_more

Sleep suspends every process, including the terminal and its network connection. The agent does not crash, it freezes mid-request, and the request times out. On wake the run has usually fallen over and has to be restarted. Keeping the Mac awake for the length of the run is the fix.

Can I let the screen turn off and lock while the agent works?expand_more

Yes, and you should. Display sleep and system sleep are separate. Hold the system awake and let the display sleep, and the Mac locks on schedule while the agent keeps working behind the lock screen. In Valpas that is the Allow display to sleep mode.

What is the simplest way to keep the Mac awake for one run?expand_more

Prefix the agent with caffeinate: caffeinate -i codex. The Mac stays awake exactly as long as the command runs. It dies with the terminal window and does nothing for a second agent you start elsewhere, which is where a menu bar tool takes over.

Can I close the lid?expand_more

Not with caffeinate or any power assertion. Closing the lid triggers clamshell sleep, which ignores them. Use an external display with the adapter, or a tool with a lid-closed mode such as Valpas Pro, which sets pmset disablesleep for the session and puts it back.

How do I know in the morning that the Mac stayed up?expand_more

Have the hold be visible. A menu bar countdown, or valpas status in the terminal, says whether the Mac was held and for how long. pmset -g log | grep -i sleep lists every sleep and wake with a timestamp if you want proof.