Keep OpenAI Codex running on a MacBook with the lid closed — and automatically let macOS sleep when Codex becomes idle.
codex-clamshell is a tiny open-source macOS LaunchDaemon for long-running AI coding agent tasks. It watches the power assertion created by Codex Desktop's Prevent sleep while running option and changes closed-lid sleep behavior only while Codex is actively working.
Close the MacBook lid while Codex is running a task: the screen turns off, but Codex keeps working. When the task finishes, pauses for input, or becomes idle, normal macOS sleep is restored automatically. If the lid is still closed, the Mac goes to sleep immediately.
The built-in Codex setting prevents idle sleep, but macOS treats lid-close (clamshell) sleep separately. Tools based only on caffeinate generally do not override closed-lid sleep without an external display.
codex-clamshell bridges that gap by promoting Codex's own activity signal to the macOS pmset disablesleep setting, then reverting it as soon as Codex stops working.
- Keeps Codex Desktop running with the MacBook lid closed
- Activates only while Codex is actively working
- Restores sleep when Codex finishes, pauses, or becomes idle
- Sleeps immediately when work ends and the lid is already closed
- Starts automatically with macOS using a system LaunchDaemon
- Recovers the normal sleep setting after a restart or interrupted run
- No background network access, telemetry, dependencies, or Homebrew
- Supports Apple Silicon and Intel Macs where
pmset disablesleepis available
In Codex Desktop, open Settings and enable Prevent sleep while running.
git clone https://github.com/llmpolska/codex-clamshell.git
cd codex-clamshell
./install.shmacOS asks for an administrator password because the helper is installed as a root-owned LaunchDaemon. The password is handled by sudo and is never stored by this project.
Codex working
└── NoIdleSleepAssertion detected
└── pmset disablesleep 1
└── lid closed → display off, Codex continues
Codex idle / finished / waiting
└── assertion disappears
└── pmset disablesleep 0
└── lid closed → Mac sleeps
The watcher checks pmset -g assertions once per second. It recognizes the Codex/ChatGPT desktop process and the Electron power assertion currently used by the application.
Check whether the service is running:
launchctl print system/pl.llmpolska.codex-clamshellCheck the current closed-lid sleep state:
pmset -g | grep SleepDisabledSleepDisabled 1— Codex is working; lid-close sleep is blocked.SleepDisabled 0or no line — Codex is idle; macOS sleeps normally.
View recent service messages:
log show --last 10m --predicate 'eventMessage CONTAINS[c] "codex-clamshell"'./uninstall.shThe uninstaller stops the service, restores disablesleep 0, and removes the installed files.
Do not put a closed MacBook in a bag while Codex is working. A running computer produces heat and may drain its battery. Use this utility on a hard, ventilated surface.
pmset disablesleep is a global macOS setting. Avoid running another closed-lid sleep utility at the same time, because two tools may compete over the same setting.
The initial implementation was verified on Apple Silicon with macOS 26.6.1 and Codex Desktop. The service also includes process-name fallbacks for Codex and ChatGPT. Application or macOS updates may change the assertion format; please open an issue with the output of pmset -g assertions if detection stops working.
OpenAI Codex, Codex Desktop, macOS prevent sleep, MacBook closed lid, clamshell mode, keep Mac awake, keep Codex running, AI coding agent, Apple Silicon, pmset disablesleep, long-running coding tasks, MacBook sleep when idle.
Built and maintained by LLM Polska — practical tools, guides, and news about large language models and AI in Poland.
If codex-clamshell keeps your agent running, consider giving the repository a star. It helps other Mac and Codex users discover the project.