OpenCode Notifier

OpenCode plugin that plays sounds and sends system notifications when session needs permission, is complete, encounters an error or question tool is invoked. Works on Linux, Windows and macOS(probably).

Installation

Add the plugin to your opencode.json or opencode.jsonc:

{
    "plugins": [ "@pranjalmandavkar/opencode-notifier@latest" ]
}

Using @latest ensures you always get the newest version of the plugin when the cache is refreshed

Restart OpenCode. The plugin will be automatically installed and loaded.

Updating

OpenCode caches plugins in ~/.cache/opencode. Plugins are not auto-updated; you need to clear the cache to get new versions.

If you use @latest

Clear the cache and restart OpenCode.

Linux/macOS:

rm -rf ~/.cache/opencode/node_modules/@mohak34/opencode-notifier

Windows (PowerShell):

Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\node_modules\@mohak34\opencode-notifier"

Then restart OpenCode - it will download the latest version automatically.

Platform Notes

The plugin works out of the box on all platforms. For best results:

• macOS: No additional setup required
• Windows: No additional setup required
• Linux: For sounds, one of these should be installed: paplay, aplay, mpv, or ffplay. For notifications, notify-send is recommended.

Configuration

To customize the plugin, create ~/.config/opencode/opencode-notifier.json:

{
  "sound": true,
  "notification": true,
  "timeout": 5,
  "showProjectName": true,
  "events": {
    "permission": { "sound": true, "notification": true },
    "complete": { "sound": true, "notification": true },
    "error": { "sound": true, "notification": true },
    "question": { "sound": true, "notification": true }
  },
  "messages": {
    "permission": "Session needs permission",
    "complete": "Session has finished",
    "error": "Session encountered an error",
    "question": "Session has a question"
  },
  "sounds": {
    "permission": "/path/to/custom/sound.wav",
    "complete": "/path/to/custom/sound.wav",
    "error": "/path/to/custom/sound.wav",
    "question": "/path/to/custom/sound.wav"
  }
}

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | sound | boolean | true | Global toggle for all sounds | | notification | boolean | true | Global toggle for all notifications | | timeout | number | 5 | Notification duration in seconds (Linux only) | | showProjectName | boolean | true | Show project folder name in notification title |

Events

Control sound and notification separately for each event:

{
  "events": {
    "permission": { "sound": true, "notification": true },
    "complete": { "sound": false, "notification": true },
    "error": { "sound": true, "notification": false },
    "question": { "sound": true, "notification": true }
  }
}

Or use a boolean to toggle both:

{
  "events": {
    "permission": true,
    "complete": false,
    "error": true,
    "question": true
  }
}

Messages

Customize notification text:

{
  "messages": {
    "permission": "Action required",
    "complete": "Done!",
    "error": "Something went wrong",
    "question": "Input needed"
  }
}

Custom Sounds

Use your own sound files:

{
  "sounds": {
    "permission": "/home/user/sounds/alert.wav",
    "complete": "/home/user/sounds/done.wav",
    "error": "/home/user/sounds/error.wav",
    "question": "/home/user/sounds/question.wav"
  }
}

If a custom sound file path is provided but the file doesn't exist, the plugin will fall back to the bundled sound.