How to Keep Codex Running on a Mac Without Sleep

Prerequisites

Before you start, you need:

• A Mac running macOS.
• Terminal, iTerm2, or another terminal emulator.
• Codex CLI installed and working.
• A Codex task that you want to keep running for a long period.
• Basic familiarity with shell commands.

Codex CLI is OpenAI's command-line coding agent and can perform development work directly from your terminal.

The important macOS command for this tutorial is caffeinate. It is built into macOS, so you do not need to install another package or keep a third-party utility running.

The simplest command is:

bash caffeinate -i

As long as that command is running, macOS is prevented from entering idle system sleep. Your display can still turn off, which is normally exactly what you want for a long-running Codex task.

Step 1: Understand Why macOS Sleep Can Interrupt Codex

When you run Codex locally from a terminal, the process depends on your Mac continuing to run.

For example, you may start:

bash codex

and ask Codex to:

• Refactor a large project.
• Run tests repeatedly.
• Install dependencies.
• Analyze hundreds of files.
• Build an Astro or Next.js application.
• Fix TypeScript errors.
• Run a long shell command.

If macOS enters system sleep while that work is happening, CPU execution and network activity may be suspended. The Codex process normally remains in memory, but it cannot continue doing useful work until the Mac wakes again.

Turning off the display is different from putting the Mac to sleep.

For long-running coding tasks, the ideal state is usually:

text Display off ↓ Mac awake ↓ Network active ↓ Codex continues running

You therefore usually want to prevent system idle sleep, not keep the display illuminated all night.

Step 2: Prevent Sleep Before Starting Codex

If Codex has not started yet, the cleanest solution is to launch it through caffeinate:

bash caffeinate -i codex

The -i option creates an assertion that prevents idle system sleep while the command is running.

The lifecycle becomes:

text caffeinate starts ↓ Codex starts ↓ Mac is protected from idle sleep ↓ Codex exits ↓ caffeinate exits ↓ Normal macOS sleep behavior returns

This is better than permanently disabling sleep because the protection exists only while you actually need it.

You can still pass normal arguments to Codex. For example:

bash caffeinate -i codex --help

For everyday use, this is the command worth remembering:

bash caffeinate -i codex

Step 3: Keep Codex Awake When the Task Is Already Running

This is the most useful scenario when you have already started a long Codex task.

Suppose Terminal 1 currently contains:

bash codex

Codex is already editing files or running commands, and you realize that your Mac may go to sleep.

Do not stop Codex.

Open a second Terminal or iTerm2 window and run:

bash caffeinate -i

Leave that command running.

There may be no visible output. That is normal.

Your terminals now effectively look like this:

`text Terminal 1

codex [Codex continues working]

Terminal 2

caffeinate -i [No output; process remains running] `

As long as caffeinate -i remains active, idle system sleep is prevented.

This is the easiest solution when Codex is already in the middle of a task because it does not require restarting, interrupting, or reconnecting the Codex session.

When Codex finishes, return to Terminal 2 and press:

text Ctrl+C

That terminates caffeinate and restores normal sleep behavior.

Step 4: Attach caffeinate Directly to the Existing Codex Process

Leaving caffeinate -i running works, but there is an even cleaner solution.

You can tell caffeinate to stay active only until the existing Codex process exits.

First, find the Codex process ID:

bash pgrep -fl codex

Example output:

text 48231 codex

The first number is the process ID, or PID.

Now run:

bash caffeinate -i -w 48231

Replace 48231 with your actual PID.

The -w option tells caffeinate to wait for that process to finish.

The lifecycle becomes:

text Existing Codex PID 48231 │ ├── caffeinate keeps Mac awake │ ▼ Codex finishes │ ▼ caffeinate automatically exits

This means you do not have to remember to return later and press Ctrl+C.

For an already-running Codex task, this is usually the best solution:

bash pgrep -fl codex

then:

bash caffeinate -i -w <PID>

For example:

bash caffeinate -i -w 48231

Step 5: Identify the Correct PID When Multiple Codex Processes Exist

You may see multiple results from:

bash pgrep -fl codex

For example:

text 48231 codex 48245 codex 48302 codex

This can happen when you have multiple Codex sessions or related child processes.

Use ps to inspect a particular PID:

bash ps -o pid,ppid,etime,command -p 48231

Example output:

text PID PPID ELAPSED COMMAND 48231 47102 32:18 codex

Useful fields include:

• PID — process ID.
• PPID — parent process ID.
• ELAPSED — how long the process has been running.
• COMMAND — command associated with the process.

If you are unsure which process belongs to your active task, the simpler alternative is still perfectly reasonable:

bash caffeinate -i

That prevents idle sleep globally while the command is running and avoids selecting the wrong PID.

Step 6: Verify That caffeinate Is Actually Working

You can inspect macOS power-management assertions with:

bash pmset -g assertions

When caffeinate -i is active, you should see an idle-sleep-related assertion in the output.

Look for information similar to:

text PreventUserIdleSystemSleep 1

You may also see a process entry identifying caffeinate as the owner of an assertion.

The exact output can vary between macOS versions, but the important point is that the relevant sleep-prevention assertion should be active.

You can also confirm that caffeinate itself is running:

bash pgrep -fl caffeinate

Example:

text 49120 caffeinate -i -w 48231

That confirms the helper process is still present.

Step 7: Let the Display Turn Off While Codex Keeps Working

For overnight or multi-hour Codex tasks, you usually do not need to keep the screen on.

Use:

bash caffeinate -i

rather than:

bash caffeinate -di

The important difference is that -d prevents the display from sleeping.

For coding agents, keeping the display illuminated provides little benefit and wastes energy.

A better setup is:

text Mac connected to power Display allowed to turn off MacBook lid left open caffeinate -i active Codex task running

The screen can become black while Codex continues running normally in the terminal.

Step 8: Understand the Useful caffeinate Options

caffeinate supports several sleep-related options.

Prevent idle system sleep

bash caffeinate -i

This is the most useful option for Codex.

Prevent display sleep

bash caffeinate -d

Use this only if you specifically need the screen to remain on.

Prevent both idle system sleep and display sleep

bash caffeinate -di

Useful when you need to continuously watch output, but unnecessary for most unattended coding tasks.

Run for a fixed duration

Use -t followed by the number of seconds.

For example, keep the Mac awake for four hours:

bash caffeinate -i -t 14400

Because:

text 4 hours × 60 minutes × 60 seconds = 14400 seconds

This is useful when you know approximately how long a task should run.

Follow a specific process

bash caffeinate -i -w 48231

This is particularly useful for attaching sleep prevention to a Codex process that is already running.

Step 9: Keep caffeinate Running After Closing Its Terminal

Normally, if you start:

bash caffeinate -i

and then close that terminal window, the process may be terminated along with the shell session.

If you need the caffeinate process itself to survive that terminal session, you can use nohup:

bash nohup caffeinate -i >/tmp/caffeinate.log 2>&1 &

The shell should print a background job and PID similar to:

text [1] 50123

You can verify it with:

bash pgrep -fl caffeinate

To stop it later:

bash pkill caffeinate

Be careful with pkill caffeinate if you have multiple intentional caffeinate processes running, because it can terminate all matching processes.

For an existing Codex process, you can combine nohup with -w:

bash nohup caffeinate -i -w 48231 >/tmp/codex-caffeinate.log 2>&1 &

Now sleep prevention automatically disappears when PID 48231 exits.

However, keeping caffeinate alive does not automatically make the original Codex terminal session survive being closed. If you want long-running terminal sessions that can be safely detached and reattached, use a terminal multiplexer such as tmux in addition to caffeinate.

Step 10: Create a Convenient Command for Future Codex Sessions

If you regularly run long Codex tasks, create a helper in your Zsh configuration.

Open:

bash nano ~/.zshrc

Add:

bash codex-awake() { caffeinate -i codex "$@" }

Save the file and reload your shell configuration:

bash source ~/.zshrc

You can now start Codex with:

bash codex-awake

Arguments are forwarded to Codex because of:

bash "$@"

For example:

bash codex-awake --help

For normal interactive use:

bash codex-awake

This gives you a simple rule:

text codex → normal Codex session codex-awake → Codex session protected from idle sleep

Avoid replacing the codex command itself with a shell function that accidentally invokes itself recursively. A separate name such as codex-awake is clearer and safer.

Step 11: Use tmux for More Reliable Long-Running Sessions

caffeinate solves the Mac sleep problem, but it does not solve every terminal-session problem.

For especially long tasks, consider combining it with tmux.

Start a tmux session:

bash tmux new -s codex

Run Codex:

bash codex

Then open another terminal and prevent sleep:

bash caffeinate -i

You can detach from tmux with:

text Ctrl+B, then D

Later, reconnect with:

bash tmux attach -t codex

This combination protects against two different problems:

`text caffeinate ↓ Prevents idle system sleep

+

tmux ↓ Keeps the terminal session alive when you detach `

For long unattended Codex work, this is a much more robust setup than depending on a normal terminal window alone.

Step 12: Know What caffeinate Does Not Protect Against

caffeinate is useful, but it should not be treated as a guarantee that every possible interruption is prevented.

In particular, do not assume caffeinate -i protects you from:

• Shutting down the Mac.
• Restarting macOS.
• Losing battery power.
• Killing the Codex process.
• Closing a terminal in a way that terminates Codex.
• Network outages.
• Explicitly terminating caffeinate.
• Every sleep behavior associated with closing a MacBook lid.

For a MacBook running an unattended task, the safest practical setup is usually:

• Connect the MacBook to power.
• Leave the lid open.
• Allow the display to turn off.
• Run caffeinate -i or attach it with -w.
• Use tmux when terminal-session persistence matters.

Avoid relying on caffeinate as a way to run a MacBook indefinitely with the lid closed. Lid-close behavior is different from ordinary idle sleep and depends on the Mac's hardware and operating conditions.

Common Issues & Troubleshooting

Codex is already running. Do I have to restart it?

No.

Open another terminal and run:

bash caffeinate -i

That takes effect without restarting the existing Codex session.

For automatic cleanup, find the Codex PID:

bash pgrep -fl codex

Then attach caffeinate:

bash caffeinate -i -w <PID>

caffeinate shows no output

That is expected.

This command:

bash caffeinate -i

normally stays in the foreground without continuously printing status messages.

Verify it with:

bash pgrep -fl caffeinate

or:

bash pmset -g assertions

I pressed Ctrl+C in the caffeinate terminal

That stops caffeinate.

Your Codex process in another terminal is not necessarily affected, but macOS can resume its normal idle-sleep behavior.

Restart sleep prevention with:

bash caffeinate -i

I closed the caffeinate terminal

If the caffeinate process terminated with the terminal, sleep prevention is no longer active.

Start it again, or use:

bash nohup caffeinate -i >/tmp/caffeinate.log 2>&1 &

I closed the Codex terminal

caffeinate does not preserve the shell session itself.

If closing the terminal terminates Codex, use tmux for future long-running jobs:

bash tmux new -s codex

The Mac went to sleep after I closed the lid

Do not treat caffeinate -i as a universal override for MacBook lid-close sleep.

For unattended Codex tasks, leave the MacBook open and let only the display sleep.

The display turned off. Is Codex still running?

Usually, yes, provided the Mac itself remains awake.

With:

bash caffeinate -i

the display is still allowed to sleep while idle system sleep is prevented.

This is normally the preferred configuration.

I see several Codex PIDs

Inspect them using:

bash ps -o pid,ppid,etime,command -p <PID>

If you still cannot confidently identify the right process, simply run:

bash caffeinate -i

instead of using -w.

How do I know when the Codex-specific caffeinate process stopped?

If you started it with:

bash caffeinate -i -w 48231

it should exit when PID 48231 exits.

Check with:

bash pgrep -fl caffeinate

If the relevant entry is gone, that assertion is no longer active.

Next Steps

For a Codex task that is already running, the fastest solution is simply:

bash caffeinate -i

If you want sleep prevention to disappear automatically when that particular Codex process finishes, use:

bash pgrep -fl codex

followed by:

bash caffeinate -i -w <PID>

For future Codex sessions, start them directly with:

bash caffeinate -i codex

For especially long or unattended work, combine:

text Codex + caffeinate + tmux

This gives you a practical macOS workflow where the display can turn off, the computer remains awake, the terminal session can be detached, and Codex can continue working without an avoidable idle-sleep interruption.