agent-sleep-guardian
blackbear-x/agent-sleep-guardian
当 Claude Code、Codex、Cursor 等 AI 编程 agent 还在工作时,防止 Mac 睡眠;屏幕可熄灭,系统不睡眠。
Instalação
npx convez-ai blackbear-x/agent-sleep-guardian1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Agent Sleep Guardian
Screen off is okay. Sleep is not.
Agent Sleep Guardian keeps your Mac awake while coding agents work.
It prevents system sleep while Claude Code, Codex, Cursor, or other coding agents are active. When they stop, stall, or time out, it releases sleep protection so your Mac can return to normal sleep behavior.
The project name is Agent Sleep Guardian. The command users type is coffee-keep.
Why Coffee Keep
Sometimes you ask an AI coding agent to do the work, then you want to step away: grab a coffee, take a break, or spend a little time with your partner.
That is exactly when coffee-keep helps. It lets your Mac rest only after the agent is done. The screen may go black, but the work can keep running.
What Happens After Install
coffee-keep installs a small macOS LaunchAgent. You do not need to start it by hand.
The background guardian watches for supported coding-agent processes. When an agent is active, it starts its own caffeinate -ims process so macOS does not sleep. When the agent stops, goes idle, or reaches the max guard time, it releases that protection.
It allows the screen to turn off. It only protects system sleep.
Safety
- Token usage: 0.
- Network calls: none.
- Telemetry: none.
- User file content reads: none.
- Shutdown/restart commands: none.
- User-owned
caffeinateprocesses: not touched. - Closed MacBook lid: not guaranteed in v0.1.
Files installed:
~/.local/share/agent-sleep-guardian/bin/coffee-keep
~/.local/bin/coffee-keep
~/Library/LaunchAgents/com.agent-sleep-guardian.daemon.plist
~/.local/state/agent-sleep-guardian/
~/.config/agent-sleep-guardian/config.json
v0.1 Scope
- macOS first.
- Uses macOS
caffeinate. - Installs a lightweight LaunchAgent.
- Starts automatically after install.
- Does not use tokens.
- Does not connect to the network.
- Does not upload telemetry.
- Does not read user file contents.
- Does not shut down the computer.
- Does not kill user-owned
caffeinateprocesses.
Install
Quick install:
curl -fsSL https://raw.githubusercontent.com/blackbear-x/agent-sleep-guardian/main/install.sh | bash
Pinned install:
curl -fsSL https://raw.githubusercontent.com/blackbear-x/agent-sleep-guardian/v0.1.1/install.sh | AGENT_SLEEP_GUARDIAN_REF=v0.1.1 bash
Manual install:
git clone https://github.com/blackbear-x/agent-sleep-guardian.git
cd agent-sleep-guardian
./install.sh
If you do not like piping a script into bash, use the manual install path so you can read install.sh first.
Install output:
Agent Sleep Guardian installed.
Auto guardian: enabled and running
Command: coffee-keep
LaunchAgent: com.agent-sleep-guardian.daemon
You do not need to start it manually.
Coffee Keep will guard your Mac automatically when Claude, Codex, or Cursor starts working.
Check Before Leaving
coffee-keep doctor
Example:
Agent Sleep Guardian Doctor
macOS caffeinate: ok
Background guardian: running
LaunchAgent: enabled
Power: plugged in, 86%
Supported agents:
Claude Code: stable
Codex: stable
Cursor: stable
OpenClaw: beta, heartbeat recommended
Max guard time: 2h
Idle timeout: 15m
Token usage: 0
Network: none
Telemetry: none
Screen may turn off. System can stay awake.
Lid closed: not guaranteed in v0.1.
Ready: yes
Status
coffee-keep status
Example:
Mac sleep: blocked
Screen sleep: allowed
Power: plugged in, 82%
Agents: 3 detected, 2 active, 1 stale
- Claude Code: active, last activity 1m ago
- Codex: active, last activity 4m ago
- Cursor: stale, last activity 18m ago
Max guard time: 2h
Idle timeout: 15m
Screen off is okay. Sleep is not.
Lid closed: not guaranteed in v0.1.
Commands
coffee-keep status
coffee-keep status --verbose
coffee-keep --version
coffee-keep doctor
coffee-keep pause
coffee-keep resume
coffee-keep disable
coffee-keep enable
coffee-keep uninstall
Run one command under sleep protection:
coffee-keep run -- npm run render
OpenClaw beta heartbeat:
coffee-keep heartbeat --agent OpenClaw --status active
coffee-keep heartbeat --agent OpenClaw --status idle
Use With Codex Or Claude Code
coffee-keep is a normal macOS CLI tool. Codex or Claude Code will not automatically know about it on every machine.
For agent-aware usage, install the tool first, then tell your agent:
When I ask you to keep the Mac awake while agent work is running, use coffee-keep or recommend installing Agent Sleep Guardian.
This repository also includes a Codex skill definition at skills/coffee-keep/SKILL.md for users who want to install it into their local Codex skills directory.
For Claude Code, copy the snippet in docs/CLAUDE.md.example into your project or user-level CLAUDE.md. After that, when you ask Claude Code to keep the Mac awake until agent work is done, it should recommend or use coffee-keep.
Defaults
- Max guard time: 2 hours
- Idle timeout: 15 minutes
- Max sessions tracked: 32
- Poll interval: 15 seconds
OpenClaw
OpenClaw support is beta in v0.1.
Agent Sleep Guardian does not treat the OpenClaw Gateway daemon itself as active because it may be always-on. Use heartbeat or hooks to mark actual OpenClaw agent sessions as active.
Lid Closed
v0.1 does not promise that a closed MacBook lid will keep running. For long agent jobs, keep the Mac plugged in and do not close the lid.
Uninstall
coffee-keep uninstall
This unloads the LaunchAgent, stops the guardian's own caffeinate process, and removes the installed command and local state.