If you have ever handed Claude Code a complex, long-running task only to return to a dead session after closing your MacBook lid, you are not alone. The culprit is not a bug in Anthropic's agent, but macOS itself. When a Mac enters sleep mode, it suspends every active process, severs network connections, and terminates SSH sessions. This behavior is by design, yet it fundamentally conflicts with the workflow of persistent, autonomous coding agents that require uninterrupted execution.

The Technical Reality of Sleep

It is crucial to understand that the agent is not killed during sleep; it is frozen. The CPU stops executing instructions, and the process state is held in memory. However, the external dependencies are not so forgiving. By the time the machine wakes up, the API connection used by the agent has typically timed out, and any in-flight tool calls have failed. On a laptop, a closed lid triggers sleep within seconds unless explicitly overridden. Contrary to popular belief, a lock screen or screensaver does not induce this state; only the sleep timer, low battery, or the physical lid sensor do.

Immediate Workarounds: Caffeinate and Power Settings

For single tasks, macOS offers the caffeinate utility, which prevents idle sleep while a command runs. Running caffeinate -i claude keeps the system awake until the agent exits, though adding the -d flag is necessary to keep the display active for screen-driving tools. However, caffeinate fails when the lid is closed, as the hardware switch overrides software assertions. For a more permanent solution on desktops or plugged-in laptops, administrators can disable sleep entirely using sudo pmset -a sleep 0 and sudo pmset -a disksleep 0. Enabling wake-on-network (womp 1) adds resilience if the machine does inadvertently drop.

Handling the Closed Lid and Terminal Sessions

The most common point of failure is the 'clamshell' rule, where a MacBook sleeps with the lid closed unless connected to power and an external display. To force a laptop to stay awake with the lid shut, users must execute sudo pmset -a disablesleep 1. This approach carries risks: the laptop will generate heat on soft surfaces and drain the battery rapidly if unplugged, potentially leading to unclean shutdowns. Furthermore, if the machine stays awake but the session drops, the issue is likely the terminal window closing or SSH disconnecting. The robust fix is using a terminal multiplexer like tmux. By running tmux new -s agent before launching Claude Code, the session persists even if the window closes or the network hiccups, allowing you to reattach later with tmux attach -t agent.

Key Takeaways

  • macOS sleep suspends processes and drops network connections, causing Claude Code API timeouts and failed tool calls.
  • caffeinate prevents idle sleep but is overridden by the physical lid switch on MacBooks.
  • sudo pmset -a disablesleep 1 allows lid-closed operation but risks overheating and battery drain.
  • Using tmux ensures the agent session survives terminal closures, SSH drops, and Wi-Fi interruptions.
  • The same sleep and session management principles apply to other CLI agents like OpenAI's Codex.

The Bottom Line

Running a 24/7 autonomous agent on a laptop is a hack, not a architecture. While pmset and tmux are essential survival tools, the honest fix for serious agent work is moving to a dedicated, always-on machine like a Mac mini or cloud instance. Stop fighting the hardware and build a stable environment.