opencode-notifier
OpenCode plugin that plays sounds and sends system notifications when permission is needed, generation completes, errors occur, or the question tool is invoked. Works on macOS, Linux, and Windows.
Quick Start
For OpenCode 1, add the package to opencode.json:
{
"plugin": ["@mohak34/opencode-notifier@latest"]
}
For OpenCode 2, use plugins:
{
"plugins": ["@mohak34/opencode-notifier@latest"]
}
Restart OpenCode. The package contains both implementations; you do not select a version manually. V2 loads the package's terminal component automatically in the interactive CLI.
OpenCode 2 delivery
Sounds, desktop popups, terminal bells, Ghostty notifications, and focus detection run in the terminal client. Custom commands run once per event on the server, including when no terminal is open. This uses the existing command configuration; no external notification service is bundled.
With a remote server, put sound and popup settings on your local computer and custom-command settings on the server. Event-command script paths refer to the server's filesystem. Click-command paths refer to the computer displaying the notification. Focus suppression applies to local alerts, not server commands. Each attached terminal receives alerts for its project. On one computer, clients with the session's family open in a tab or current route take priority over unrelated clients in the same project. If several eligible clients have it open, only the first to claim the event alerts. If none have it open, an eligible client still alerts after a brief fallback grace; terminals on other computers each alert.
Clients publish their open-session IDs in private temporary files, refreshed once per second and removed on disposal. Dead processes and presence older than five seconds are ignored. If the registry or client-local UI APIs are unavailable, alerts fail open through the existing event claim.
opencode run and Desktop/Web clients do not load this terminal component, so they receive no plugin sound, popup, or bell. Server commands still run. V1 delivery and its enableOnDesktop behavior are unchanged.
V2 already includes a notification plugin. To avoid duplicate built-in alerts, add "-opencode.notifications" to the existing plugins list in ~/.config/opencode/cli.json:
{
"plugins": ["*", "-opencode.notifications"]
}
Keep any other entries in that list, with "-opencode.notifications" after matching enable entries such as "*" or "opencode.*". A later enable entry can turn the built-in alerts back on. plan_exit remains a V1 event; V2 has no equivalent plan-ready signal, so that setting is inactive there. client_connected is best-effort: terminal startup for local alerts, server plugin startup for custom commands.
What it does
You'll get notified when:
- OpenCode needs permission to run something
- Your session finishes
- An error happens
- The question tool pops up
There's also subagent_complete for when subagents finish, and user_cancelled for when you press ESC to abort -- both are silent by default so you don't get spammed.
Setup by platform
macOS: Nothing to do, works out of the box. Shows the Script Editor icon.
Linux: Should work if you already have a notification system setup. If not install libnotify:
sudo apt install libnotify-bin # Ubuntu/Debian
sudo dnf install libnotify # Fedora
sudo pacman -S libnotify # Arch
For sounds, you need one of: paplay, aplay, mpv, or ffplay
Windows: Works out of the box. But heads up:
- Only
.wav files work (not mp3)
- Use full paths like
C:/Users/You/sounds/alert.wav not ~/
WSL: Set customIconPath to a file on the Windows filesystem to avoid icon-path translation issues. You can copy an icon from this repository's logos folder. The path is passed to snoretoast-*.exe.
In opencode-notifier.json config:
{
"showIcon": true,
"customIconPath": "C:\\Users\\YourName\\Documents\\opencode-logo-dark.png"
}
Config file
Create ~/.config/opencode/opencode-notifier.json with this example configuration. Omitted settings use their defaults:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
