Add setting to disable automatic caffeinate/sleep prevention

[shyal]

Summary

Claude Code spawns caffeinate -i -t 300 repeatedly during active sessions, preventing macOS sleep — including lid-close sleep. There is no setting to disable this behavior.

User Stories

Story 1: Disable sleep prevention
As a developer using Claude Code on a laptop, I want to disable the automatic caffeinate spawning so that my Mac sleeps when I close the lid, even during an active session.

Current Behavior

• Claude Code spawns caffeinate -i -t 300 as a child process during active sessions
• The process respawns after each 300s expiry, so killall caffeinate is ineffective
• The source is shipped as a minified cli.js bundle so users cannot patch it
• Community tools (cc-caffeine, cc-caffeinated) exist to add caffeinate support for headless/remote use cases, but none provide a way to disable the built-in behavior

Acceptance Criteria

• A user-configurable setting (e.g. disableCaffeinate in ~/.claude/settings.json) disables automatic caffeinate spawning
• When disabled, no caffeinate child processes are spawned during sessions
• When enabled (default), current behavior is preserved

Edge Cases

• Setting should be respected across session restarts
• Existing community hooks that add their own caffeinate should not conflict

[somiandras]

It seems Claude Code sometimes spawns these caffeinate processes even when idle (eg. stopped at a user question or finished the task). I just had a couple of sessions on, one completely idle one went rogue and kept my laptop awake. After exiting it the others seem to work as intended: spawn caffeinate while working, letting sleep when idle (I couldn't find any documentation around this behaviour so I just assume what is intended and what not). This happened multiple times in the past week or so.

[sai3563]

I'm too facing the same issue.

Even if the claude session isn't doing anything (all prompts replied & nothing being processed), it still keeps running caffeinate -i -t 300 frequently preventing my macbook from going to sleep.

We use a corporate oauth login that auto-refreshes every 8 hours by opening a new chrome tab. If this expires at night, it launches a new tab for oauth login every 5 minutes so I wake up to like 20+ tabs in the morning.

There needs to be an option to disable this, this is buggy and should not prevent sleep when the claude session isn't doing anything.

[qiuruiyu]

I am also facing the same issue. My mac always keeps awake after closing the lid, and the battery drops to zero fast

[LineskipSteve]

User story:
As a developer using Claude Desktop on a Mac, I should be able to sleep my computer while Claude Desktop is idle and not have the battery completely drain overnight.

[LineskipSteve]

If Electron has the ability to allow sleep (as all apps should), then this should be considered a BUG in Claude Desktop, not an enhancement. Actually, I would argue that even if Electron had no such ability, it's still a bug to choose Electron to build it on.

[jpranta]

Adding a concrete data point and a suggested fix direction.

Lost a working session to this. A Claude Code session was running unattended on battery. Its caffeinate -i -t 300 child held PreventUserIdleSystemSleep the whole time, so as the charge ran low the laptop never idle-slept — and because macOS only writes the hibernation image at the moment of sleep, it never hibernated either. It drained to 0% and hard-shut-off, losing the session. (/var/vm/sleepimage had a stale placeholder timestamp, confirming no recent hibernation occurred.) This matches the "battery drops to zero fast" reports above.

Confirmed the source via the process tree:

Terminal.app
└─ login → zsh
   └─ claude                 (the CLI)
      └─ caffeinate -i -t 300

And pmset -g showed sleep 0 (sleep prevented by caffeinate, powerd), with pmset -g assertions attributing PreventUserIdleSystemSleep to the caffeinate process.

Suggested fix, in priority order:

1. Don't assert the wakelock on battery power — keeping the machine awake makes sense on AC for a long unattended run, but on battery it produces exactly this dead-battery failure. An AC-only default would fix the worst case without any config.
2. Failing that (or in addition), the requested opt-out switch — caffeinateEnabled: false in settings.json, or an env var / CLI flag like CLAUDE_CODE_DISABLE_CAFFEINATE=1 / --no-wakelock.

Environment: Claude Code CLI on macOS (Darwin 25.5.0, Apple Silicon). Repro: start a session and run pmset -g assertions | grep caffeinate.