Prevents the system from sleeping while any OpenCode agent session runs. In OpenCode v2, the wake lock also remains active for OpenCode-managed background shell commands until they exit. OpenCode v1 remains session-only: its wake lock is released when all sessions go idle or error.
While OpenCode blocks waiting for user input — a permission prompt
(permission.asked), the question tool (question.asked), or a form
(form.created) — the session's lock entry is temporarily held back so the system
may sleep while you are away. The lock is re-acquired when you answer or dismiss
(permission.replied, question.replied, question.rejected, form.replied,
form.cancelled), provided the session is still active. A reply that arrives after
the session has gone idle or failed does not resurrect the lock.
Works on macOS (via caffeinate) and Linux (via systemd-inhibit,
including Fedora + KDE Plasma, Ubuntu, Arch, and any other systemd-based
distro). On other platforms the plugin loads but does nothing.
The plugin uses shared lock entries in /tmp/opencode-wakelock/sessions/ and
runs one platform-specific inhibitor while any entry remains. Session and shell
entries share this directory; shell entries use the shell- prefix. The
inhibitor stops only when no session or shell entries remain.
- A busy
session.statusacquires a lock for that session. session.idleorsession.errorreleases that session's lock.permission.asked/question.asked/form.createdhold the session's entry back so the system may sleep while awaiting user input;permission.replied/question.replied/question.rejected/form.replied/form.cancelledre-acquire it if the session is still active.- V1 tracks sessions only; background shell commands do not keep the wake lock active.
- The context hook acquires a lock for each session, and
session.waitreleases it. shell.createdacquires an independent lock for that shell ID.shell.exited(including nonzero exit, timeout, or kill) orshell.deletedreleases it.permission.asked/question.asked/form.createdhold the session's entry back so the system may sleep while awaiting user input;permission.replied/question.replied/question.rejected/form.replied/form.cancelledre-acquire it if the session is still active.- Only OpenCode-managed shells are tracked. Detached descendants that continue after the shell wrapper exits are not covered.
- Shells already running when the plugin reloads are not rediscovered because the V2 plugin context has no shell inventory API.
| Platform | Command | Blocks |
|---|---|---|
| macOS | caffeinate -i sh -c <watchdog> |
System idle timer |
| Linux | systemd-inhibit --what=sleep:idle ... sh -c <watchdog> |
System sleep + idle timer |
On Linux, systemd-inhibit is used because it ships with systemd (installed by
default on Fedora, Ubuntu, Arch, openSUSE, Debian, etc.) and works regardless
of desktop environment — KDE Plasma, GNOME, XFCE, sway, headless servers, and
remote SSH sessions all work the same way.
On both platforms, the watchdog checks the server PIDs in the shared session and shell entries once per second. If a server crashes or is killed, its entries no longer keep the inhibitor alive. The inhibitor exits when no tracked owner is alive, even without plugin cleanup or an OpenCode restart. Work owned by other running OpenCode servers continues to keep the inhibitor active.
If systemd-inhibit is unavailable (e.g. non-systemd distros like Void or
Artix, or minimal containers), the plugin logs a warning and continues without
a wake lock — OpenCode itself is unaffected.
To verify the lock is active on Linux:
systemd-inhibit --list
# look for "opencode-wakelock" in the outputThe package supports both OpenCode v1 and v2. Use the configuration key for the OpenCode version you run.
OpenCode v2:
{
"plugins": ["opencode-wakelock"]
}OpenCode v1:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["opencode-wakelock"]
}No additional dependencies are required. caffeinate ships with macOS and
systemd-inhibit ships with systemd on Linux.
- Multi-platform: macOS and Linux out of the box
- Multi-instance safe: Multiple OpenCode instances can run in parallel without conflicts
- Automatic cleanup: Stale session files from crashed instances are automatically detected and removed
- Efficient: Only one inhibitor process runs, shared across all instances
- Zero overhead on unsupported platforms: Plugin loads but does nothing on Windows / BSD
bun install --frozen-lockfile
bun test
bun run buildTests use isolated mock OS state and do not start real inhibitors. Watchdog tests also run real shell processes against temporary lock entries to verify shutdown after SIGKILL and continued protection across multiple servers.
To release a new version, bump the package.json version and push to main.
The workflow tests the package, publishes it to npm, then creates a GitHub release
tagged v<version> with generated notes and a link to the npm package. The tag
targets the published package's npm gitHead, not a later commit on main.
The workflow waits for npm registry propagation before creating the GitHub release.
The workflow uses the built-in GITHUB_TOKEN; no extra release token is needed.
If the npm version or GitHub release already exists, that step is skipped, so
rerunning the workflow can create a missing GitHub release without republishing
the package. You can also run the workflow manually.
If workflow files changed after the published commit, GitHub can reject creating
its historical tag with GITHUB_TOKEN. In that case, a maintainer must first push
v<version> at the npm gitHead, then rerun the workflow. Existing tags are
checked against the published commit and are never moved.