opencode-notifier

OpenCode plugin that plays sounds and sends system notifications when permission is needed, generation completes, or errors occur. Works on macOS, Linux, and Windows.

Installation

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

{
  "plugin": ["@mohak34/opencode-notifier@latest"]
}

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

To pin a specific version:

{
  "plugin": ["@mohak34/[email protected]"]
}

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.

If you use a pinned version (e.g., @0.1.7)

1. Update the version in your opencode.json:

   {
     "plugin": ["@mohak34/[email protected]"]
   }

2. Clear the cache (see commands above)

3. Restart OpenCode

Check installed version

Linux/macOS:

cat ~/.cache/opencode/node_modules/@mohak34/opencode-notifier/package.json | grep version

Windows (PowerShell):

Get-Content "$env:USERPROFILE\.cache\opencode\node_modules\@mohak34\opencode-notifier\package.json" | Select-String "version"

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,
  "events": {
    "permission": { "sound": true, "notification": true },
    "complete": { "sound": true, "notification": true },
    "error": { "sound": true, "notification": true }
  },
  "messages": {
    "permission": "OpenCode needs permission",
    "complete": "OpenCode has finished",
    "error": "OpenCode encountered an error"
  },
  "sounds": {
    "permission": "/path/to/custom/sound.wav",
    "complete": "/path/to/custom/sound.wav",
    "error": "/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) |

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 }
  }
}

Or use a boolean to toggle both:

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

Messages

Customize notification text:

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

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"
  }
}

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

Troubleshooting

macOS: Notifications not showing (only sound works)

Update to v0.1.8 or later - this version includes a fix for macOS notification events.

If notifications still don't work after updating:

1. Install terminal-notifier via Homebrew:

   brew install terminal-notifier

2. Check notification permissions:

   • Open System Settings > Notifications
   • Find your terminal app (e.g., Ghostty, iTerm2, Terminal)
   • Make sure notifications are set to Banners or Alerts
   • Also enable notifications for terminal-notifier if it appears in the list

Linux: Notifications not showing

1. Install notify-send:

   # Debian/Ubuntu
   sudo apt install libnotify-bin
   
   # Fedora
   sudo dnf install libnotify
   
   # Arch
   sudo pacman -S libnotify

2. Test if it works:

   notify-send "Test" "Hello"

Linux: Sounds not playing

Install one of these audio players: paplay, aplay, mpv, or ffplay.

# Debian/Ubuntu (PulseAudio)
sudo apt install pulseaudio-utils

# Or install mpv
sudo apt install mpv

Windows: Notifications not showing

1. Open Settings > System > Notifications
2. Make sure notifications are enabled
3. Check that your terminal app has notification permissions

General: Plugin not loading

1. Check your opencode.json syntax:

   {
     "plugin": ["@mohak34/opencode-notifier@latest"]
   }

2. Clear the cache and restart:

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

License

MIT