Overnight runs fail for six reasons: lid sleep, idle sleep, network, permission prompts, battery, and heat. Clamshell, a Mac menu bar app, handles the first two: it keeps the Mac awake with the lid closed, with no sudo and no external display.
An animated MacBook with a coding agent deploying a website from its terminal. The Option key is held and the lid closes: the display goes black, but the Mac stays awake, so a dimmed copy of the terminal keeps working above the closed laptop while its front edge fills with light. When the deploy is done, a pointer shows how to lift the lid. Opening it wakes the Mac to its lock screen, which unlocks to the finished run: deployed, with the live address. The lid can then be opened and closed freely.
Clamshell for Mac keeps the Mac awake with the lid closed while armed. No sudo, no monitor. Free for 7 days, then $9.99 once.
Apple Silicon, macOS 14+. Notarized by Apple. 3.6 MB. Or install with Homebrew: brew install --cask clamshell. On your phone? Send the Mac download link to yourself.
Overnight agent runs on a MacBook usually fail for one of six reasons: the lid closed and the Mac slept, idle sleep kicked in, the network dropped, the agent stopped to ask for permission, the battery ran out, or the Mac got too hot. Keep the Mac awake with the lid shut, pre-approve what the agent needs, plug in on a hard surface, and log a heartbeat so you can check the run in the morning. For the lid, Clamshell for Mac is a menu bar app that keeps an Apple Silicon MacBook awake with the lid closed, without an external monitor or sudo.
Quick answer
If the job can run in the cloud
Claude Code cloud sessions and Codex Cloud: send it there. Your laptop does not need to stay awake.
If it must run locally
A CLI agent, a desktop agent on a local project, a model served by Ollama, a long build: keep the Mac awake with the lid closed.
Remove every prompt the agent could stop on
Use the tool's own non-interactive flags and the narrowest permissions that work.
Plug in, ventilate, log a heartbeat
Then run a two-minute lid-closed check before bed.
Run an agent overnight with Clamshell for Mac in three steps
- Install Clamshell for Mac. Download the free trial from clamshell.dev, or run
brew install --cask clamshell, and open it once. It runs in the menu bar. - Arm it before bed. Right-click the menu bar icon so it stays armed until you turn it off, then open the menu and check that it says Armed. Pressing both Option keys arms for the next close only, so opening the lid again ends it.
- Start the agent, then close the lid. Plug in, start the Claude Code, Codex or other agent run with its permissions decided up front, and close the lid on a hard surface. The run continues on this Mac through the night with the built-in display black.
Disarm in the morning, or let the wrapper below do it. Clamshell for Mac is a closed-source app that costs $9.99 once after a 7-day trial; unlike Apple's clamshell mode, it needs no external display. Clamshell for Mac is available only from clamshell.dev, on Setapp and through Homebrew. It is not on the Mac App Store; App Store apps named Clamshell are from other developers.
On this Mac, in the cloud, or on a server
There are three places an overnight agent can run while your laptop is shut. Pick by what the task needs; each one is a real option.
| Where it runs | Fits when | What keeps running | Effort | Limits |
|---|---|---|---|---|
| This Mac, lid closed, with Clamshell for Mac | The task needs this Mac: your checkout as it is now, local MCP servers, simulators, local models, apps you are signed in to | Every local process: the agent and its tools, builds, tests, local models, and phone remote control of the session | Arm Clamshell, check it shows armed, close the lid. $9.99 once after a 7-day trial | Apple Silicon and macOS 14 or later. Keep the Mac on a desk with air around it, ideally on power. Permission prompts still wait for you. At serious or critical heat, or at 20% on battery, Clamshell disarms and the Mac sleeps |
| The vendor's cloud: a Claude Code cloud session or a Codex cloud task | The task needs only the repository and the tools the cloud environment provides | The task on the vendor's servers. Anthropic says a cloud session keeps running after you close your laptop; OpenAI says a Codex cloud task can keep working while your computer is asleep | Connect your GitHub account, push your branch, then start the task from the vendor's web or app interface | It works on a copy of the repository, not your live checkout, and cannot reach anything else on your Mac. Anthropic counts cloud session usage toward your plan's limits |
| Your own server, in tmux | You already have a machine that stays on, such as a VPS, a Linux box or a desktop Mac, with the project and its tools set up there | Everything inside the tmux session. tmux keeps programs running in the background after you detach, and you reattach over SSH | Set up the machine, SSH keys, the repository, the agent and its logins, then tmux new -s agent and later tmux attach -t agent | A server to pay for or keep on, and to maintain. It cannot reach files or apps on your MacBook. Closing the MacBook only drops your SSH connection |
Clamshell for Mac is the way to do the first row without a monitor or admin rights. The rows also mix: cloud tasks for work that needs only the repository, the closed Mac for the jobs that need this Mac. The rest of this page is about the first row.
What stops an overnight run
Lid sleep
Morning sign: work stopped around the time you closed the lid. Fix: an external display setup, pmset disablesleep, or a lid-sleep tool.
Idle sleep, lid open
Morning sign: work stopped some minutes after you walked away. Fix: caffeinate -i around the command, or any lid-closed method.
Network drop
Morning sign: API errors, timeouts, a disconnected remote session. Fix: stable Wi-Fi or Ethernet; check VPN and captive portals.
Permission prompt
Morning sign: the agent waited all night on one question. Fix: pre-approve with the tool's flags or settings.
Battery
Morning sign: the Mac is off or asleep with a flat or low battery. Fix: plug in; set a low-battery cutoff.
Heat
Morning sign: slow progress, or a safety disarm. Fix: hard, open surface; fewer parallel jobs.
Agents can also stop for reasons no keep-awake tool can touch: a usage or rate limit, an API error, a crashed process, or a task the agent decided was done. The heartbeat and log below help you tell these apart from sleep.
Local or cloud: check where the agent runs
Cloud: the laptop is only a window
Anthropic's docs say a Claude Code cloud session runs on cloud infrastructure and keeps running after you close your laptop. OpenAI's docs say each Codex Cloud task has its own workspace and can keep working while your computer is asleep. For those, the laptop is only a window.
Local: the Mac must stay awake
Everything that executes on the Mac needs the Mac awake: Claude Code in your terminal or in the desktop app with Local selected, the Codex CLI, Cursor's agent working in your local editor, local models served by Ollama, Xcode or cargo builds, Docker containers, and test suites. Phone remote control, such as Claude Code Remote Control or Codex Remote, steers that local session; the work still runs on the Mac.
Keep the Mac awake with the lid closed
- Apple's closed-display mode needs an external display, keyboard and mouse, and power. It is supported and works well if you already have that desk setup.
sudo pmset -a disablesleep 1works with no hardware, but it is global, needs admin rights, has no timer, and applies on battery. The risk is forgetting it. How to check and undo it.- Clamshell keeps the Mac awake with the lid closed only while armed, shows its state in the menu bar, needs no admin rights, and a restart always brings back normal lid sleep. Arm it from the menu, with Option held while closing the lid on Macs with a lid angle sensor, from Shortcuts, or with
clamshell://arm.
Clamshell for Mac keeps your agents running with the lid closed. Free for 7 days, then $9.99 once for one Mac.
Apple Silicon, macOS 14+. Notarized by Apple. 3.6 MB. Or install with Homebrew: brew install --cask clamshell. Also on Setapp.
Pre-flight checklist
- Commit or branch first. Start the run from a clean state so the morning diff shows only the agent's work.
- Decide the permissions up front. Claude Code's non-interactive mode takes
-pwith--allowedToolsor--permission-mode, and recent versions add--permission-prompts nonefor unattended runs.codex execis read-only by default;--sandbox workspace-writeallows edits in the workspace. For other tools, find their equivalent. Grant the narrowest access that lets the task finish. - Write output to a file. Terminal scrollback is not a record. Log the agent's output and a timestamp heartbeat.
- Plug in. A long run on battery is a gamble. If you must use battery, set a cutoff (see below).
- Pick the surface. A hard, flat desk with open air around the vents. Not a bed, sofa, closed drawer or bag.
- External displays can stay connected. Clamshell arms with or without one.
- Arm and confirm. Check the menu bar shows armed. A URL request or shortcut is not confirmation.
- Run a two-minute proof. Start the heartbeat, close the lid for two minutes, open it, and confirm the timestamps kept arriving.
Two commands help while the lid is still open, and only then. caffeinate -i ./night.sh holds off idle sleep until the script exits, and pmset -g assertions in a second Terminal window should list an entry owned by caffeinate. That proves idle sleep is held off with the lid open. It says nothing about a closed lid, which caffeinate does not cover; for that, trust the two-minute proof and pmset -g log.
A wrapper with a heartbeat
This zsh wrapper requests arming, writes a timestamp every minute, runs the agent, and requests disarming on exit. Swap the agent line for Codex, a build, or any other command.
#!/bin/zsh
set -e
LOG="$HOME/agent-night-$(date +%Y%m%d).log"
open "clamshell://arm"
( while true; do date -u '+beat %Y-%m-%dT%H:%M:%SZ' >> "$LOG"; sleep 60; done ) &
HB=$!
trap 'kill $HB 2>/dev/null; open "clamshell://disarm" || true' EXIT
claude -p "Run the test suite and fix any failures" \
--allowedTools "Bash,Read,Edit" >> "$LOG" 2>&1
date -u '+done %Y-%m-%dT%H:%M:%SZ' >> "$LOG"
The open calls only deliver requests; confirm the armed state in the menu before closing the lid. The trap does not run if the shell is killed. Clamshell's core does not detect when the agent finishes; this script is what ends the session.
Power, heat and ventilation
With the lid closed, the built-in display stays black. If your agents do not need the screen, leave Clamshell's Agent Screen module off (the default) and the display sleeps instead, which uses less battery. The rest depends on the work. A mostly idle agent waiting on API responses is light. Local builds, test suites and especially local models are heavy, and they draw the same power and make the same heat as they would with the lid open, with less room for air to move if the Mac sits on something soft.
- Plug in for overnight runs. On battery, a heavy workload can empty it well before morning.
- Leave the vents clear. Closed-lid MacBooks still need airflow. Never run a heavy job in a bag or under a blanket. The closed-lid safety guide covers surfaces, heat and battery care.
- Thermal safety is always on in Clamshell. If macOS reports serious or critical thermal pressure, Clamshell disarms toward normal lid sleep and refuses to arm until the Mac cools. That pauses your run on purpose. If it happens, cut parallel jobs or move the Mac.
- Low battery cutoff. Clamshell's Disarm on low battery is on by default in General settings, so an unplugged run lets the Mac sleep at 20% instead of draining flat.
Check the run in the morning
- Read the heartbeat. Timestamps a minute apart all night mean the Mac stayed awake. A gap marks when it stopped.
- Match gaps to sleep.
pmset -g loglists sleep and wake events with timestamps. A sleep entry at the gap points to sleep; no sleep entry points to the agent, the network or a limit. - Read the agent's last output in the log. A question, a permission denial, or an API error explains most stops.
- Review the diff with
git statusandgit diffbefore accepting anything. - Disarm. If the wrapper did not, disarm from the menu bar before the Mac goes into a bag.
What Clamshell does and does not do
Does
Clamshell keeps an Apple Silicon MacBook on macOS 14 or later awake with the lid closed, keeps the built-in display black, and locks the Mac when you open the lid. It works on battery and power and stays armed when you plug in or unplug.
Does not
Its core does not detect agents or stop when a task finishes, and it does not answer permission prompts, keep Wi-Fi connected, or make a sleeping Mac reachable. Keeping the Mac awake removes one cause of stalled runs; the checklist above handles the rest.
Frequently asked questions
Can I run Claude Code overnight with the MacBook lid closed?
Yes, if the Mac stays awake. A local Claude Code session pauses when lid sleep starts. Use an external display setup, pmset disablesleep, or a lid-sleep tool such as Clamshell, and pre-approve the tools the run needs so it does not wait on a prompt. Claude Code cloud sessions keep running without your laptop.
Why did my AI agent stop overnight even though the Mac was awake?
Common causes are a permission prompt nobody answered, a network drop, a usage or rate limit, an API error, or the agent deciding the task was finished. A timestamp heartbeat in a log file shows whether the Mac was awake, and the agent's last output usually shows why it stopped.
Is it safe to leave a MacBook running all night with the lid closed?
It is reasonable on a hard, ventilated surface and connected to power. Do not run heavy work in a bag or on soft furnishings. Clamshell disarms toward normal lid sleep if macOS reports serious or critical thermal pressure.
Does Clamshell know when my agent is finished?
Not by default. Clamshell's core does not detect Claude Code, Codex, Cursor or any other agent; its optional Agent Status, Agent Notifications and Finish Work, Then Sleep modules show what Claude Code and Codex agents are doing, notify you, and can let them finish before the Mac sleeps. Wrap the job in a script that opens clamshell://disarm on exit, or disarm from the menu bar when you are back.
Can I run a local model with Ollama overnight on a MacBook?
Yes, with the Mac awake, plugged in and ventilated. Local models are among the heaviest workloads a laptop runs, so expect sustained heat and power draw, and check the heartbeat log in the morning.
How do I check whether my Mac slept during the night?
Run pmset -g log and look for sleep and wake entries around the time your log shows a gap. Compare them with a timestamp heartbeat written by your wrapper script.
Related guides
- Keep Ollama or LM Studio serving with the lid closed
- Check on agents over SSH with the lid closed
- Does Claude keep running if you lock your laptop?
- Arm Clamshell from Claude Code hooks
- Does Mac sleep burn your Claude Code usage limit?
- Does Codex Goal mode keep running with the lid closed?
- How to keep a MacBook awake with the lid closed
- Best apps to keep a MacBook awake, lid closed or open
- Claude Code Remote Control with the lid closed
- Use Codex from your phone with the lid closed
- Is it safe to run a MacBook with the lid closed?
- Keep Claude Code running with the lid closed
- Keep Codex running when you close your MacBook lid
- Keep a Cursor agent running with the lid closed
- Keep a MacBook awake with the lid closed on battery
- Why caffeinate does not work with the lid closed
- Compare Clamshell, Amphetamine, pmset and Apple's setup
- Claude Code cloud vs local: when your Mac must stay awake
- Computer use and iOS Simulator with the lid closed
- Codex "Keep this Mac awake" with the lid closed
Sources checked September 29, 2026: Anthropic's Claude Code cloud sessions and non-interactive mode docs, OpenAI's Codex Cloud and non-interactive mode docs, Apple's external display guidance for a closed laptop, and the macOS pmset(1) manual. Clamshell behavior is described from its app source and FAQ. The "On this Mac, in the cloud, or on a server" table and the caffeinate and pmset -g assertions lines were checked on November 14, 2026 against Anthropic's Remote Control docs, OpenAI's Codex Cloud docs, the tmux wiki and pmset(1). No new hardware testing was done for this page. Clamshell is an independent app, not affiliated with Anthropic, OpenAI, Cursor or Ollama. Product names belong to their owners.