Lidwork Guides App Store · $9.99

Keep Claude Code / Codex running with the MacBook lid closed

You start a long agent run, close the laptop, and come back to a session that stopped five seconds after you left. Here's a setup that doesn't.

Updated · by Sasha Yakovlev, maker of Lidwork

Quick answer

A coding agent stops when the Mac sleeps, and a MacBook sleeps when you close the lid unless an external display is attached. To keep Claude Code or Codex running: start it inside tmux, disable lid sleep (sudo pmset -a disablesleep 1, then undo with 0 — or use an app that restores it automatically, like Lidwork, which Claude Code can switch on at the start of a session and off at the end with two hooks), keep the Mac on power for long runs, and check in over SSH or Tailscale.

Coding agents like Claude Code and Codex are long-running processes on your Mac. They read files, run tests, call the model API and write code for minutes or hours. Close a MacBook's lid without a monitor, and macOS puts the whole system to sleep within seconds: the process freezes, network connections drop, and the agent picks up — or errors out — only when you open the lid again.

There's no special “agent mode” that changes this. You need two things: a session that survives you walking away, and a Mac that doesn't sleep when the lid shuts.

Option 0: do you need your own Mac at all?

If the task doesn't depend on your local machine, a cloud session may be simpler: Anthropic's Claude Code cloud sessions run on Anthropic's infrastructure and keep going after you close your laptop. Running locally still makes sense when the agent needs your local files, credentials, simulators, GPUs, Docker setup or a private network. The rest of this guide is for that case.

1. Run the agent inside tmux

Start the agent in a terminal multiplexer, so the session lives independently of any window or SSH connection:

brew install tmux        # once
tmux new -s agent        # start a named session
claude                   # or: codex
# detach with Control-B, then D

Later — from the same Mac, or over SSH — reattach with tmux attach -t agent. screen works too if you prefer it.

2. Stop the lid from sleeping the Mac

This is the step most setups get wrong. Common advice is caffeinate, and it's half right: caffeinate -i claude keeps the Mac from idle sleep for exactly as long as the agent runs, which is perfect with the lid open. It does not survive closing the lid without an external display. (Why: caffeinate explained.)

For a closed lid you have three choices:

  • Clamshell mode: power + external display + keyboard. Great on a desk, useless in a bag.
  • The manual switch: sudo pmset -a disablesleep 1 before you close the lid, and sudo pmset -a disablesleep 0 when you're back. Free, but if you forget the second command the Mac stays awake until the battery dies.
  • An app that does it for you. Lidwork keeps the Mac awake with the lid closed from the menu bar (no sudo, no password) and lets it sleep again when you switch it off, when the battery reaches your cutoff, when the Mac gets too hot, or — via its small background part — when the app itself crashes or hangs.

The simplest setup: let Claude Code switch Lidwork on and off

If you use Lidwork, you don't have to remember to turn it on. Claude Code can run a small command when a session starts and another when it ends. Lidwork listens for two links: lidwork://on keeps the Mac awake, lidwork://off lets it sleep normally again.

Paste this into ~/.claude/settings.json (for every project) or a project's .claude/settings.json:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "open -g 'lidwork://on?hours=8'" }] }],
    "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "open -g lidwork://off" }] }]
  }
}
  • What it does: you start claude, the star in the menu bar turns yellow; you end the session, it turns grey and your Mac sleeps normally again. -g keeps Lidwork in the background so nothing jumps in front of your terminal.
  • Why hours=8: it's a safety cap. If a session never ends cleanly, Lidwork still stops after 8 hours.
  • Awake only while Claude is answering? Use UserPromptSubmit with open -g lidwork://on and Stop with open -g lidwork://off instead. Stop runs after every reply, so pair it with UserPromptSubmit, not SessionStart.
  • The safety stops still apply. Whatever the hooks say, Lidwork lets the Mac sleep when the battery reaches your limit (10%, 20% or 30%) or when the Mac gets too hot.
  • Several sessions at once: the first one that ends switches keep-awake off for all of them.
  • If Lidwork can't confirm your App Store purchase, on explains why instead of turning on; off always works.

3. Battery and heat: the honest part

An agent run is mostly waiting on the network plus bursts of compiling and testing. Battery drain depends on what the agent runs: a test suite or a Docker build uses far more power than an agent reading files.

  • Plug in for runs longer than an hour or two, or set a battery cutoff so the Mac sleeps before it's empty.
  • Mind the bag. A closed Mac has almost no airflow. A walk across town is fine; hours sealed in a backpack under load is not. Fanless MacBook Airs warm up fastest.
  • Let it breathe at the destination. Take it out of the bag even if you don't open it.

4. Check in from your phone

Enable Remote Login (System Settings → General → Sharing) and connect over SSH. Outside your home network, a mesh VPN like Tailscale gives the Mac a stable address without opening ports. Then:

ssh you@your-mac       # from a terminal app on your phone
tmux attach -t agent   # watch it, answer its questions, detach again

Agents often stop to ask for permission. Decide before you leave which commands it may run without asking, so a question doesn't block the whole run while you're on the train.

5. When it's done: put sleep back

Whatever method you used, finish by checking the switch is off:

pmset -g | grep SleepDisabled   # want: SleepDisabled 0

If it says 1 and you're not sure why, sudo pmset -a disablesleep 0 restores normal sleep.

A checklist for overnight runs

  1. On power, on a hard surface, lid closed or open.
  2. Agent inside tmux, with permissions set so it doesn't stall on a question.
  3. Lid sleep disabled — and a plan for re-enabling it.
  4. SSH or Tailscale tested before you leave the room.
  5. In the morning: keep-awake is off (grey star in Lidwork, or pmset -g shows SleepDisabled 0 if you used the manual switch).

Coming next: a free Claude Code plugin

The two hooks above work today. Next we're building a free, open-source Claude Code plugin that keeps the Mac awake only while the agent is actually working, and lets it sleep while it waits for you. Read the announcement.

FAQ

Does Claude Code keep running when I close my MacBook lid?

Only if the Mac stays awake. Without an external display, a MacBook sleeps seconds after the lid closes, and the agent pauses with it. caffeinate does not prevent that; a lid-sleep override or an app like Lidwork does.

Can Claude Code turn keep-awake on and off by itself?

Yes, with hooks. A SessionStart hook runs open -g 'lidwork://on?hours=8' and a SessionEnd hook runs open -g lidwork://off, so the Mac stays awake only while a session runs.

Is it safe to run an agent overnight with the lid closed?

On a desk and on power, yes for most workloads. On battery, set a battery limit; in a bag, airflow is close to zero, so avoid long heavy runs there.

What happens if Lidwork crashes during a run?

Its background part notices and turns its lid hold off — right away after a crash, within about 30 seconds after a hang — so the Mac can sleep normally again.