convez.ai
Agente
blackbear-x

agent-sleep-guardian

blackbear-x/agent-sleep-guardian

Ver no GitHub
InicialPluginScore · de 0 a 100

当 Claude Code、Codex、Cursor 等 AI 编程 agent 还在工作时,防止 Mac 睡眠;屏幕可熄灭,系统不睡眠。

Instalação

$npx convez-ai blackbear-x/agent-sleep-guardian

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v0.1.1
Issues abertas
0
Contribuidores
1

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 caffeinate processes: 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 caffeinate processes.

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.

Ver o original no GitHub

Bom para

Relacionados