Repository navigation
v1.0.0
What it does
Keeps your computer awake while OpenCode is actually working — and lets it sleep again the moment every session goes idle.
Long agent runs (model streaming, tool execution, compaction, rate-limit retries) routinely take minutes with no user input. Default OS power settings treat that as idle and suspend mid-prompt. This plugin holds a system sleep inhibitor for exactly the duration of the work, then releases it.
- macOS —
caffeinate -dims -w <server pid> - Linux —
systemd-inhibit --what=sleep:idle, bound to the server pid - Other platforms — inert no-op
Install
opencode plugin add opencode-stay-awakeor in opencode.json:
{ "plugin": [["opencode-stay-awake", { "graceMs": 5000 }]] }How it decides "busy"
Deliberately event-driven, not polling. Paired session events open and close a per-session work-item counter:
| opens | closes |
|---|---|
session.execution.started |
.succeeded / .failed / .interrupted |
session.step.started |
.ended / .failed |
session.tool.called, session.tool.input.started |
.success / .failed, .input.ended |
session.text.started |
.ended |
session.reasoning.started |
.ended |
session.compaction.started |
.ended / .failed |
session.shell.started |
.ended |
A tool call that runs for minutes (a build, a test suite) keeps its work item open, so the inhibitor survives long silences instead of being released mid-run. A quiet period, a grace period and a stale cap guarantee it is always released and can never be held forever by a lost end event.
Every inhibitor is bound to the OpenCode server pid, so a crashed or killed server releases it on its own — the machine can never be wedged awake.
Notable design decisions
session.get()is not consulted. On v2 itsoutcomeandtime.idleare only written when an execution settles, so an actively generating session still reports the previous run's outcome. Trusting it would drop running sessions mid-flight.- Events are de-duplicated by id. One server process usually hosts several instances of this plugin (one per workspace) and every instance receives every event, so without de-duplication the shared counters would move once per instance instead of once per event.
- Never throws during
setup(). Any unexpected error degrades to a no-op, so a failure can never silently disable sleep protection.
Requirements
- OpenCode v2 (2.0.x), including the desktop app
- Zero dependencies, Node >= 18
- MIT licensed