Keep Mac awake while Claude Code runs

Why a Mac sleeps during a long agent run

A Mac can idle-sleep during an agent run if no power assertion prevents idle sleep, so check the running process rather than assuming its sleep behavior.

Apple describes the setting as sleep after a specified duration of inactivity. Lock Screen uses the same idea in the labels “Turn display off on battery when inactive” and “Turn display off on power adapter when inactive.” The pmset command (man pmset on macOS) documents separate system and display sleep timers, measured in minutes, and describes how processes can override power settings with I/O Kit power assertions.

Apple’s I/O Kit docs split the two cases. System sleep is Sleep from the Apple menu or a closed laptop lid. Idle sleep is what happens “when there has been no device or system activity during the interval the user selects in the Energy Saver preferences.” Apple’s Energy Efficiency Guide for Mac Apps explains how apps declare lengthy user-initiated work and shows PreventUserIdleSystemSleep in assertion output. Check for that assertion during the run; CPU activity and an explicit sleep assertion are different signals.

The man page (man caffeinate on macOS) uses caffeinate -i make as its example: the command holds an idle-sleep assertion while make runs. Use the same wrapper for a local agent when you want an explicit hold. The assertion follows the process lifetime, whether you are typing a prompt or waiting for the next response.

Some processes do keep a Mac awake. Apple tells you to check Activity Monitor’s CPU column if the Mac will not sleep, and the sleep and wake guide describes waking with a key press or a mouse or trackpad click.

To see whether anything is holding sleep right now, run pmset -g assertions. The what’s keeping this Mac awake guide reads that output.

What happens to an agent run when the Mac sleeps

macOS sleep changes the power state of the hardware a local agent uses; Apple’s sleep documentation does not specify whether a particular agent request will fail or resume. Apple says the machine consumes much less energy, and its I/O Kit guide describes drivers preparing hardware for sleep.

Apple treats sleep as a low-power state, not a shutdown. Waking is faster than a cold start. Shared services on the network are a separate switch: Wake for network access lets the Mac wake briefly so other people can reach a shared printer or file. Apple describes that option in terms of access to shared services; use an explicit idle-sleep hold for your local agent process.

Check the agent’s output after waking the Mac before deciding whether the run finished. A sleep guide cannot tell you what happened to that agent’s request. To prevent idle sleep during a local run, use the process wrapper below and inspect pmset -g assertions while it is active.

Closing the lid is a different path. Apple’s I/O Kit docs call lid-close a system sleep, not idle sleep. Keep Awake With Lid Closed is coming in a Napless update and is not available yet. Until then, leave the lid open or follow the MacBook lid-closed guide.

How to use caffeinate with Claude Code or Codex

The caffeinate command can keep a Mac awake for the life of Claude Code or Codex by creating an idle-sleep assertion while that process runs.

caffeinate ships with macOS (man caffeinate on macOS). The Claude Code quickstart starts the CLI with claude, and the Codex CLI docs use codex. Pass either utility to caffeinate and the assertion lasts until that utility exits.

-i is the idle-sleep flag. -w waits for an already-running process ID instead.

caffeinate -i claude

caffeinate -i codex

caffeinate -w 12345

Replace 12345 with the process ID of the agent you want to watch; 12345 is only an example. -w is ignored if you also pass a utility on the same line.

The display can still sleep under -i alone. Add -d if you want the screen on too. -s prevents system sleep, and the man page says that assertion is valid only on AC power.

Open Terminal.
cd into the project the agent should edit.
Start the agent with caffeinate -i in front of the command you already use.
Leave that Terminal session open until the agent finishes. Quitting caffeinate drops the assertion.

For every flag, see the caffeinate command guide. The hold follows the process lifetime, including later turns within that same interactive process, and ends when the process exits. The man page documents process exit and timeout controls, but does not document a temperature-based stop.

How Napless agent mode holds the Mac awake

Napless Pro agent mode, coming soon, keeps a Mac awake by installing hook files for Claude Code, Codex, Grok, Cursor, and Gemini CLI, then holding idle sleep during a turn or session within the documented limits.

Napless itself is free. Napless Pro is $7.99 one time, up to 3 Macs, and is not for sale yet. Agent mode is a Pro feature on the build from napless.io. The Napless help page is the source for the paths and timers below.

Settings → Triggers → AI Agents has an Install button per tool. The sheet shows the path and the JSON Napless will add. Remove deletes only Napless’s hooks.

Tool	Hooks live in
Claude Code	`~/.claude/settings.json`
Codex	`~/.codex/hooks.json`
Grok	`~/.grok/hooks/napless.json`
Cursor	`~/.cursor/hooks.json`
Gemini CLI	`~/.gemini/settings.json`

Claude Code, Codex, and Grok stay awake while a turn runs, for up to 10 minutes after the last prompt, even if that turn is still going. Cursor stays awake while a turn runs, for up to 60 minutes after the last prompt. Gemini CLI stays awake while a Gemini session is open.

Codex will not run a new hook until you trust it. In the Codex CLI, type /hooks, open the Napless handler, and trust it. OpenAI’s hook docs say a non-managed command hook is skipped until you review and trust the exact definition, and a changed hook definition requires review again.

Agent mode needs Napless running. Turn on Open at Login so the menu bar app starts when you log in. Apple keeps that list in System Settings → General → Login Items & Extensions. An organization can turn Agent Mode off with the managed key NAPDisableAgentHooks, documented in Napless for IT.

For tools outside those five, use the process or app options below.

How to keep the Mac awake for other agents

Napless Pro, coming soon, will cover agents without hooks through napless run -- <command> for CLIs or a trigger that keeps the Mac awake while a chosen desktop app is open.

napless run -- aider

napless run -- make release

If napless is not on your PATH:

'/Applications/Napless.app/Contents/Helpers/napless' run -- aider

napless run is a Pro Terminal-job watch: the hold lasts until that command exits, as described in the Pro feature summary. After Pro launches, use it for Antigravity CLI, Devin CLI, Factory Droids in the terminal, Amp, Pi, OpenCode, Kiro CLI, Cline CLI, and Aider.

For a desktop app, use the Pro “keep awake while a chosen app is open” trigger and pick that app. That is the path for Cursor if you would rather watch the app than use hooks, for Google Antigravity IDE, and for Devin Desktop. Cognition renamed Windsurf to Devin Desktop; the announcement is on Devin’s site.

Check where the agent executes before choosing a hold. Amp’s CLI docs, for example, distinguish local threads from threads in an orb or on a runner. A keep-awake hold on your Mac applies to this Mac; it does not control the remote machine.

Until Pro ships, caffeinate -i in front of the same CLI, or caffeinate -w on the desktop app’s PID, is the workaround. The keep a Mac awake pillar lists the other timers and System Settings paths.

Tool-by-tool: how Napless holds and when they end

Napless Pro, coming soon, will hold the Mac awake through hooks, napless run jobs, or app watches, ending on turn completion, a time limit, process exit, or app closure.

Tool	How Napless keeps the Mac awake	When the hold ends
Claude Code	Pro agent-mode hooks in `~/.claude/settings.json`	When the turn ends, or at the 10-minute limit after the last prompt
Codex	Pro agent-mode hooks in `~/.codex/hooks.json` (trust once with `/hooks`)	When the turn ends, or at the 10-minute limit after the last prompt
Grok	Pro agent-mode hooks in `~/.grok/hooks/napless.json`	When the turn ends, or at the 10-minute limit after the last prompt
Cursor	Pro agent-mode hooks in `~/.cursor/hooks.json`, or keep-awake while Cursor is open	When the turn ends or at 60 minutes after the last prompt (hooks), or when Cursor quits (app watch)
Gemini CLI	Pro agent-mode hooks in `~/.gemini/settings.json`	When the Gemini session closes
Antigravity	`napless run --` for the CLI, or keep-awake while the IDE is open	When that command exits, or when the app quits
Devin Desktop (formerly Windsurf)	Keep-awake while the app is open	When the app quits
Devin CLI	`napless run --`	When that command exits
Factory Droids	`napless run --` for the CLI, or an app trigger for the IDE hosting Droids	When that command exits, or when the chosen IDE quits
Amp	`napless run --` for a local CLI, or keep-awake while the app is open	When that command exits, or when the app quits
Pi	`napless run -- pi`	When that command exits
OpenCode	`napless run --` for the CLI, or keep-awake while the desktop app is open	When that command exits, or when the app quits
Kiro	`napless run --` for the CLI, or keep-awake while the IDE is open	When that command exits, or when the app quits
Cline	`napless run --` for the CLI, or keep-awake while Cline Desktop is open	When that command exits, or when the app quits
Aider	`napless run -- aider`	When that command exits

The table describes Napless Pro features that are coming soon. caffeinate -i and caffeinate -w work on the Mac you have today.

Keep the laptop plugged in and ventilated

For a long agent run, use a stable surface with good ventilation as Apple recommends, and connect power if you need to avoid relying on battery charge.

Apple’s temperature page says to use the laptop on a stable work surface that allows for good ventilation, not a bed, a pillow, or bedding. Ambient range is 50° to 95°F (10° to 35°C). Do not block the vents. On Macs with fans, Apple describes faster fans during intensive work as normal cooling.

caffeinate -s is valid only on AC power (man caffeinate on macOS), which is a useful hint even if you stay on -i.

Napless heat protection lives in Settings → General → Safety as Stop If Your Mac Gets Too Hot. It is on by default. When the thermal state is serious or critical, Napless stops keeping the Mac awake and the menu says “Paused because your Mac is hot.”

A timed session ends there. After the thermal state stays at fair or cooler for 5 minutes, automatic keep-awake can start again. Start a timed session yourself if you still want one.

Napless can also stop on low battery. Napless for IT lists a battery floor of 20 percent by default, with a minimum of 10 percent; battery protection is off by default. Plug the MacBook in before you walk away from a multi-hour agent. Leaving it on the charger does not override heat stop.

Download Napless from napless.io/download. Requirements are macOS 13 or later, Apple silicon and Intel. The app is signed and notarized by Apple.

Questions

Why does a Mac sleep while Claude Code is running?

macOS can idle-sleep after inactivity when no active assertion prevents it. Check pmset -g assertions during the run rather than assuming Claude Code holds one. Wrap claude in caffeinate -i, or use Napless Pro agent mode when it ships.

What does caffeinate -i claude do?

The caffeinate command starts Claude Code and holds an idle-sleep assertion until that process exits. The display can still sleep unless you also pass -d.

Does Napless hook Aider, Cline, or Windsurf?

Napless installs hooks only for Claude Code, Codex, Grok, Cursor, and Gemini CLI. Other agents can use napless run or keep-awake while a chosen app is open; both are Napless Pro features, coming soon.

What happens if I close the lid during an agent run?

Keep Awake With Lid Closed is not available yet. Closing a MacBook lid can still put the Mac to sleep. Leave the lid open, or see the lid-closed guide, until that Napless update ships.

Why does Codex ignore the Napless hooks?

Codex requires you to trust a non-managed hook once with /hooks before that hook can run. New or changed hooks are skipped until you trust them again.