opencode-suspend-inhibitor

Prevents Linux/GNOME from suspending or idling the screen while an OpenCode agent session is actively running. Releases the inhibitor the moment all sessions go idle or error. Supports multiple parallel OpenCode instances.

Install

Published on npm: opencode-suspend-inhibitor

Add to ~/.config/opencode/opencode.json or opencode.jsonc (merge into your existing config):

{
  "$schema": "https://opencode.ai/config.json",
  // ... your other settings ...
  "plugin": ["opencode-suspend-inhibitor"]
}

Restart OpenCode.

Alternatives

Several OpenCode plugins prevent sleep while the agent is busy. Pick by platform and desktop environment:

| Plugin | npm / repo | Platforms | Mechanism | Notes | |--------|------------|-----------|-----------|-------| | This plugin | opencode-suspend-inhibitor · GitHub | Linux + GNOME | gnome-session-inhibit (suspend:idle) | Multi-instance via session files; --app-id ai.opencode.desktop | | opencode-sleep-inhibitor | opencode-sleep-inhibitor · GitHub | Linux (systemd), macOS | systemd-inhibit / caffeinate -dis | Cross-platform; treats any status.type !== "idle" as active | | opencode-wakelock | opencode-wakelock · GitHub | macOS only | caffeinate -i | Multi-instance via session files |

Platform support

| Platform | Status | Alternative | |-------------------------------|--------|-------------| | Linux + GNOME Session Manager | Supported | — | | Linux + systemd (non-GNOME) | Not supported | opencode-sleep-inhibitor | | macOS | Not supported | opencode-wakelock or opencode-sleep-inhibitor | | Windows | Not supported | — |

Requirements

• Linux with GNOME Session Manager
• gnome-session-inhibit on PATH (Debian/Ubuntu: package gnome-session-bin)
• OpenCode >= 1.14.0

How it works

Hooks into OpenCode session lifecycle events:

| Event | Condition | Action | |-------|-----------|--------| | session.status | status.type: "busy" | Register session; start inhibitor if needed | | session.status | status.type: "idle" | Deregister session; stop inhibitor when none remain | | session.idle | — | Deregister session; stop inhibitor when none remain | | session.error | — | Deregister session; stop inhibitor when none remain |

When at least one session is active, the plugin runs:

gnome-session-inhibit \
  --inhibit-only \
  --inhibit suspend:idle \
  --reason "OpenCode Agent is actively working" \
  --app-id ai.opencode.desktop

This blocks system suspend and idle screen lock/dim while the agent is busy.

Features

• Multi-instance safe: Multiple OpenCode instances can run in parallel without conflicts
• Automatic cleanup: Stale session files from crashed instances are pruned when the recorded PID is dead
• Efficient: One shared gnome-session-inhibit process across all instances
• Graceful no-op: On non-Linux or when the binary is missing, the plugin loads but does nothing (one warning in logs)

Multi-instance

Session state is tracked via files in /tmp/opencode-suspend-inhibitor/sessions/. Each file is named by OpenCode sessionID and stores the owning OpenCode process PID. A single gnome-session-inhibit process is shared across all OpenCode instances on the machine; it stops only when no active sessions remain.

Development

See DEVELOPMENT.md for project setup, testing, build workflow, issue tracking (beads), and AI agent conventions. See CHANGELOG.md for release history.

Related

• OpenCode plugins