Skip to main content

OpenCode Notifier

tip

592 GitHub stars — Desktop notifications and sound alerts for permission requests, task completion, and error events.

Overview​

OpenCode Notifier sends native OS desktop notifications and plays sound alerts when events occur during a session. Instead of watching the terminal, you can work in other windows and be notified when the agent needs attention, completes a task, or encounters an error.

When to Use​

ScenarioBenefit
Long-running buildsGet notified when compilation or tests finish
Permission promptsReceive alerts when the agent needs approval
Background agentsMonitor delegated tasks without polling
Error recoveryImmediate notification when something fails

How It Works​

  1. Event subscription — The plugin subscribes to session events (idle, error, permission, completion).
  2. Notification dispatch — When a matching event fires, the plugin sends an OS notification.
  3. Sound alert — Optionally plays a sound to draw attention.
  4. Action integration — Some notifications support click-to-focus back to the terminal.

Installation​

{
  "plugin": ["opencode-notifier"]
}

Configuration​

Basic Setup​

{
  "plugin": ["opencode-notifier"],
  "opencode-notifier": {
    "permission": true,
    "completion": true,
    "errors": true
  }
}

Selective Notifications​

{
  "opencode-notifier": {
    "permission": true,
    "completion": false,
    "errors": true,
    "sounds": true,
    "sound_file": "/path/to/custom-sound.wav"
  }
}

Disable Sounds​

{
  "opencode-notifier": {
    "sounds": false,
    "permission": true,
    "completion": true
  }
}

Usage​

Once configured, notifications appear automatically:

  • Permission request — A notification appears: "OpenCode needs approval to run: git push"
  • Task complete — Notification when the agent finishes: "Session completed in 2m 34s"
  • Error — Notification on failure: "Build failed with 3 errors"

Clicking the notification typically brings your terminal window to focus.

Best Practices​

Match Notifications to Your Workflow​

  • Enable permission notifications when you step away during agent work.
  • Disable completion notifications for rapid iterative tasks.
  • Use sounds only for critical events to avoid notification fatigue.

Customize Sound Files​

  • Use distinct sounds for permission vs. error events.
  • Keep sounds short (under 2 seconds) for quick recognition.

Don't Over-Notify​

  • Too many notifications reduce their effectiveness.
  • Only enable the event types that matter for your current workflow.

GitHub​

  • Repo: mohak34/opencode-notifier
  • npm: opencode-notifier
  • Topics: notifications, desktop, alerts, sounds
  • Category: Notifications / Session UX