Agent Caffeine — Development skill for Claude Code

agent-caffeine

Keep macOS awake while a CLI coding agent is working — and let it sleep when the work cannot progress.

Long agent runs die when the Mac sleeps mid-stream. The API connection goes quiet, the client watchdog fires, and the agent stops with something like `API Error: Response stalled mid-stream`. `caffeinate` alone fixes that by never letting the machine sleep, which costs battery for every idle session you leave open.

`agent-caffeine` holds the assertion only while an agent actually works, and drops it when the network has been down long enough that staying awake is pointless.

$ agent-caffeine status
updated       2026-08-13 10:14:02
awake held    true
network ok    true
detection     lease
leases        2 live
  1a6d741a-7775-4753-a10e-e6c7d27e9b7e     claude pid=58707 age=6s
  01998c4f-0e5f-7a91-b0d2-3f1a2c7d8e44     codex  pid=72076 age=41s

How it decides

A **lease** is one file per agent session under `~/.local/state/agent-caffeine/leases/`. Your agent's own hooks create and refresh it. The daemon reads that one directory — it never scans the process table.

A lease dies three ways, so a crashed session cannot leak the assertion and pin your Mac awake:

1. the Stop / SessionEnd hook removes it,
2. the owning pid disappears,
3. its mtime passes the TTL (default 600 s), which also covers a long model turn that fires no hook.

Every 15 s the daemon reads the leases, probes the network, and decides:

Condition	Action
A live lease exists	Hold caffeinate -i -m -s
No live lease	Release — the Mac may sleep
TLS probe fails 3 times	Cycle Wi-Fi, at most once per 5 min, only if Wi-Fi power is on
Network down for 10 min	Release — do not burn battery on work that cannot progress
Network returns	Hold again, if a lease is live

Install

go build -o ~/.local/bin/agent-caffeine .
agent-caffeine install      # writes the config and the launchd agent, then starts it

`install` is idempo