Guide · Overnight agent runs

Run AI coding agents overnight on a Mac without sleep

You kick off a long Claude Code refactor or a Codex batch, glance at the clock, and step away — maybe to bed, maybe to a meeting. The plan is simple: let the agent grind through the work while you are gone and read the results in the morning. Then you come back to a sleeping Mac and a run that stalled hours ago. This guide covers why macOS sleep kills overnight agent runs, the power and session settings that keep a run alive, and how Perked automates the whole thing — staying awake only while your agents work, then letting the Mac sleep again the moment they finish.

Why macOS sleep kills an overnight run

macOS has two different kinds of sleep, and only one of them is harmless. Display sleep just turns the screen off — your agent keeps running behind a black display, which is exactly what you want overnight. System (idle) sleep is the problem: after a stretch with no keyboard, trackpad, or mouse activity, macOS suspends the whole machine. The CPU parks, background processes freeze, and network connections drop. A coding agent counts as none of that activity, so from the system's point of view an unattended Mac looks idle even while an agent is hammering the CPU — and it gets put to sleep mid-run.

The common assumption is that a plugged-in Mac stays awake on its own. It does not. Idle sleep has a timer that fires on AC power too — the default is just longer than on battery. So the laptop you left charging on your desk still drops off an hour or two into the job, and the agent's session dies with it. Getting an overnight run to finish means defeating idle sleep specifically, without also leaving the Mac awake forever after the work is done.

The power settings that matter

macOS exposes its sleep behavior through the built-in `pmset` tool. It is worth knowing what the relevant keys do — and where driving them by hand falls short:

• pmset -g prints your current power settings. Look at `sleep` (minutes of idle before the system sleeps — `0` means never) versus `displaysleep` (minutes before the screen alone turns off). Turning off display sleep does nothing to stop the system from sleeping; those are separate timers.
• sudo pmset -c disablesleep 1 is the blunt instrument: it stops the Mac from idle-sleeping on AC power entirely. It needs an admin password, it is global and easy to forget you left on, and it keeps the machine awake whether or not any work is happening — so it can quietly run down a battery or overheat a closed laptop until you remember to set it back to `0`.
• AC vs. battery. pmset keeps separate profiles: `-c` sets the charger (AC) profile, `-b` the battery profile, and `-a` both at once. macOS sleeps much more aggressively on battery, so for an overnight run you generally want the Mac on power — but even on AC the idle-sleep timer still applies unless you change it.

The catch with all of this is that it is a manual, global, all-or-nothing switch you have to remember to flip before the run and unflip afterwards — and if you forget, the Mac never sleeps again on its own.

Keep the session alive: tmux and detached runs

Staying awake is only half the problem. If you start an agent inside a terminal over SSH, or in a window you later close, the run can die when that connection or session goes away — even on a Mac that never slept. The fix is a persistent session. Start the agent inside tmux (or screen), detach from it, and the process keeps running under the session; you can reattach later from anywhere and pick up exactly where it left off. Running the command with `nohup` or as a background job serves a similar purpose for one-off scripts.

But session persistence and sleep are two separate concerns, and it is easy to conflate them. tmux keeps your process attached to a living session; it does nothing to stop macOS from idle-sleeping the machine underneath it. A detached tmux session on a sleeping Mac is still frozen — the process is preserved, but it is not making progress. You need both: a persistent session so the run survives disconnects, and a stay-awake so the Mac keeps running the session through the night.

Know when it's done: completion notifications

An overnight run is more useful if it can tell you it finished — or that it stopped and needs you. A few lightweight ways to get a signal without babysitting the terminal:

• osascript -e 'display notification "Run finished" with title "Agent"' fires a native macOS notification from the end of your command, so a banner is waiting when you get back. Chain it after the agent with `&&` so it only pings on success.
• say "the run is done" speaks an alert out loud — handy when you are in the same room but away from the screen. A plain terminal bell (`printf '\a'`) works too if your terminal is set to flag it.
• A push to your phone. A one-line curl to a service like ntfy or Pushover, appended to the command, sends a notification to your phone — useful when you have genuinely left the house. Several agents also expose their own hooks that can run a command when a task completes.

Lock & Leave: walk away without sleeping

Leaving a Mac awake and unlocked on your desk overnight is not ideal. macOS lets you lock the screen with ⌃⌘Q, but the security-conscious move is to lock and keep the run going in one step. Perked's "Lock & Leave" does exactly that: press ⌥⌘A to lock the screen while the session stays awake and the agents keep working. The display goes dark and the machine is secured, but the run underneath never pauses — you can walk away safely and come back to finished work.

Where Perked fits

Perked is a macOS menu-bar app that automates all of this so you do not have to remember any of it. It auto-detects 22 coding agents out of the box — Claude Code, Codex, Cursor, Gemini CLI, Aider and more — plus any custom app you add, and it keeps the Mac awake only while one of them is actually running. Kick off the run and step away; Perked handles staying awake for you, no `pmset` and no flag to unset.

Because it is tied to what the agents are doing, it also solves the other half of the problem: when the last agent finishes, Perked lets the Mac sleep again on its own, so an overnight run does not turn into a Mac that stays awake all day. It is power-aware — require AC power or a battery threshold you set — it works with the lid closed, and it pairs with "Lock & Leave" so you can secure the screen without stopping the run.

It is a one-time purchase from €1 — currently €1, and whatever you pay is locked in for good.

Overnight agent runs FAQ

← Back to Perked