Caffeine Toggle / Guides

Keep Claude, Hermes, and AI agents running on a Mac

Long agent jobs fail for more reasons than sleep. This checklist covers the Mac, the process, the network, and the heat.

By Kimi Yashar · Updated August 31, 2026 · 6 minute read

Short answer: prevent system sleep before starting the agent, keep the process attached to a durable session when appropriate, plug into power, and confirm the service itself will not time out.

What sleep does to an AI task

When a Mac sleeps, local execution pauses. A terminal process does not keep making progress, downloads may stop, and network connections can break. When the Mac wakes, some tools reconnect cleanly and others exit or wait for input.

Apple describes sleep as a low-power state that keeps the Mac turned on while reducing energy use. See the current Mac User Guide.

A five-minute preflight checklist

  1. Prevent sleep. Use caffeinate -i for an open Mac, an Apple-supported clamshell setup at a desk, or a closed-lid utility.
  2. Plug in. Local models, builds, and browser automation can drain a battery quickly.
  3. Use a durable terminal session. For a shell job, tmux or a tracked background process can protect against closing the terminal window. Sleep prevention and process durability solve different problems.
  4. Check for prompts. An agent waiting for permission, a password, or confirmation is awake but not working.
  5. Leave airflow. Put the Mac on a hard surface with clear ventilation.

Claude Code and terminal agents

If the job is tied to a Terminal tab, keep that tab and its parent application open. A process manager or terminal multiplexer can help if the window closes accidentally. For a one-off command, wrap it with caffeinate:

caffeinate -i -- your-agent-command

The keep-awake assertion ends when the command exits. For a graphical app such as Hermes, a persistent background helper can own the assertion while the app continues working.

Local models are a thermal workload

A local language model can keep the CPU, GPU, and memory system active for hours. Closing the display does not make that work cooler. Monitor temperatures and power use, especially during inference, indexing, or compilation.

Never close an active MacBook and put it away. A sleeve or backpack traps heat. Keep it on a hard, open surface where you would feel comfortable leaving it under load with the display open.

Remote models have separate limits

Keeping the Mac awake protects the local client and its network connection. It cannot guarantee that a hosted model, website, API, VPN, or Wi-Fi access point will stay connected. Remote services may enforce request limits, session expiration, or their own job timeouts.

Display sleep versus Mac sleep

The display can turn off while the computer stays awake. That is usually what you want for an overnight job: no bright screen, but uninterrupted execution. Closing a MacBook lid is different because macOS treats it as forced sleep unless clamshell behavior is changed.

The closed-lid guide explains the difference and gives a physical verification test.

How Caffeine Toggle fits

Caffeine Toggle lives directly in the macOS menu bar. The full mug prevents idle sleep and applies the closed-lid override. The empty mug restores normal behavior. The visible state makes it harder to forget whether the Mac will sleep before you walk away.

The project is open source, so you can inspect the native AppKit app, sleep arguments, and safety behavior before building it.

Start the job. Fill the mug.

Download the ZIP, open it, and drag Caffeine Toggle into Applications. On first launch, Control-click the app and choose Open; if blocked, use System Settings → Privacy & Security → Open Anyway. This build is signed with an Apple Development certificate and is not yet notarized.

Download Caffeine Toggle 3.0.1