Repository navigation
Releases
v1.0.3 — bound the blind hold, make the stale cap measure progress
[1.0.3] - 2026-09-23
Fixed
- The inhibitor could be held long after the work was finished. Two related
defects let a finished session keep the machine awake:- While no plugin instance had a live event stream,
isBusy()reported busy
unconditionally and the sweeper refused to drop idle sessions, so the only
release path left wasstaleMs— up to fifteen minutes with no evidence of
any work. Reproduced against the desktop app's shared server, where the
plugin instance is disposed with the workspace and the machine then stayed
awake until the stale cap expired. The blind hold is now bounded by a new
blindMsoption (default 30s, long enough to bridge the stream's own retry
backoff). - A work item whose end event was lost (a dropped stream, a plugin reload
mid-execution) pinned its session busy for as long as the session stayed
alive, because unrelated traffic kept refreshing the session's liveness and
the stale cap — which measured arrival, not progress — never fired. The
cap now measures progress, and a finished execution also clears any leftover
work items, so a turn that ends always releases.
- While no plugin instance had a live event stream,
Changed
killInhibitornow signals throughprocess.kill(-pid, signal)instead of
ChildProcess.kill(-pid, signal). The negative pid targets the inhibitor's
process group, but the two-argumentChildProcess.killform is not portable
across the runtimes that can host the server.stop()re-checks the inhibitor a second later and escalates toSIGKILLif
it outlivedSIGTERM, so a release can no longer silently fail.
v1.0.2
What changed
npm description now names "sleep"
The description only said "keeps your computer awake", so the word sleep appeared nowhere in the package metadata. That made the package invisible to npm search opencode sleep — the most obvious query a user with this problem would type. The description now reads:
OpenCode v2 plugin that keeps your computer awake and blocks system sleep while any session is generating (macOS caffeinate, Linux systemd-inhibit)
Repository hardening
actions/checkoutandactions/setup-nodeare pinned to commit SHAs instead of floating major tags..github/dependabot.ymlkeeps those pins current, ignoring major bumps (action majors change runner requirements and defaults, so they are reviewed by hand).package-lock.jsonadded so the manifest has a lockfile..github/SECURITY.mdadded with private vulnerability reporting.
Install
opencode plugin add opencode-stay-awakeThen restart the app, or run opencode reload.
Verification
- 24/24 behavioural checks pass
node --check index.jscleannpm pack --dry-runclean- CI green
v1.0.1
Fixed
- The README's license badge was a dynamic shields.io npm badge that renders
"package not found" whenever the registry metadata is cold or is served from a
cache written before the package existed. Replaced with a static MIT badge, and
the version badge moved to the/latestvariant so its URL differs from the
cached one. Neither can report a missing package now.
Documentation
- README restructured around time-to-first-success: install, verify and
disable/remove all sit above the fold instead of several screens down. - Added a contents list, an ASCII state diagram for the busy model, a
"why not just use…" comparison against manualcaffeinate/pmset/
always-on toggles, an FAQ, and a symptom-to-cause troubleshooting table. - Documented that
opencode plugin addwrites the config key as"plugins"
(plural) while the examples use"plugin"— both are accepted and behave
identically. - Design notes record the v2 plugin contract, event envelope, the
de-duplication requirement and the BunappendFilegotcha.
No behavioural change — the plugin code is byte-identical to 1.0.0.
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