# How to Keep Codex Running on a Mac Without Sleep Learn how to keep Codex running on macOS with caffeinate, attach it to an active Codex process, and prevent long coding tasks from sleeping. Canonical URL: https://aiidelist.com/blog/keep-codex-running-mac-without-sleep Language: en Published: 2026-08-08 Updated: 2026-08-08 ## 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 ``` 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 ``` ### 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 ``` 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 ``` 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.