GUIDE
Keep your Mac awake while agents run
To keep a long agent run alive you have to hold three separate things open - system sleep, display sleep, and the lock-screen idle timer - and most keep-awake tools only handle two, which is why you still return to a login window and a stalled agent.
Part one: system sleep
caffeinate -i (or a power assertion like PreventUserIdleSystemSleep) keeps the machine from idle-sleeping. Every keep-awake utility does this.
Part two: display sleep
A separate assertion (PreventUserIdleDisplaySleep) keeps the screen on. Most tools do this too.
Part three: the one everyone forgets
The screen-saver / lock-screen idle timer is a third mechanism that power assertions do not touch. With “require password after screen saver” enabled, your Mac can lock over a perfectly awake session. The fix is periodically declaring user activity (IOPMAssertionDeclareUserActivity) - which resets the lock timer the way moving the mouse would.
What NapCat does
- Holds all three - system, display, and the activity heartbeat - during a fake nap, and automatically whenever a watched agent is working.
- Lets go the moment the last agent stops, so your normal lock behavior returns.
- Optional battery guard: release below 15% unplugged, so a forgotten overnight run can’t drain the Mac flat.
Questions
Why does my Mac still lock while caffeinate is running?
caffeinate and power assertions block system and display sleep but not the screen-saver / lock-screen idle timer. With 'require password after screen saver' on, your Mac can lock over an awake session.
How do you stop the lock screen without disabling it?
Periodically declare user activity (IOPMAssertionDeclareUserActivity), which resets the lock timer the way moving the mouse would - so your normal lock behavior stays intact the rest of the time.
What does NapCat hold open during a run?
All three: system sleep, display sleep, and the activity heartbeat that resets the lock timer - during a fake nap, and automatically whenever a watched agent is working. It lets go the moment the last agent stops.
Will it drain my battery overnight?
There's an optional battery guard that releases the hold below 15% on battery, so a forgotten overnight run can't run the Mac flat.
Related
See how to monitor multiple Claude Code sessions, set up Claude Code notifications, or read the full Claude Code support page.
Keep AI coding sessions in sight from your Mac’s notch - $7.99, once.
Download - free 2-day trial