mohak34 / opencode-notifier

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 Add this to your : Restart OpenCode. Done. 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 for when subagents finish, and 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: For sounds, you need one of: , , , or **Windows**: Works out of the box. But heads up: • Only files work (not mp3) • Use full paths like not Config file Create with the defaults: All options Global options • - Turn sounds on/off (default: true) • - Turn notifications on/off (default: true) • - How long notifications show in seconds, Linux only (default: 5) • - Show folder name in notification title (default: true) • - Include the session title in notification messages via placeholder (default: true) • - Show OpenCode icon, Windows/Linux only (default: true) • - Skip notifications and sounds when the terminal is the active window (default: true). See Focus detection for platform details • - macOS only: , , or (default: "osascript"). Use if you're running Ghostty terminal for native OSC 9 notifications • - Linux only: replace notifications in-place instead of stacking (default: false). Requires 0.8+ Events Control each event separately: fires when you press ESC to abort a session. It's silent by default so intentional cancellations don't trigger error alerts. Set or to if you want confirmation when cancelling. The property controls whether the custom command (see Custom commands) runs for that event. Defaults to for all events. Set it to to suppress the command for specific events without disabling it globally. Or use true/false for both: Messages Customize the notification text: Messages support placeholder tokens that get replaced with actual values: • - The title/summary of the current session (e.g. "Fix login bug") • - The project folder name • - Current time in format (e.g. "14:30:05") • - Global notification counter that persists across restarts (e.g. 1, 2, 3). Stored in When is , is replaced with an empty string. Any trailing separators ( , , ) are automatically cleaned up when a placeholder resolves to empty. To disable session titles in messages without changing , just remove the placeholder from your custom messages. The and placeholders also work in custom command args. Sounds Use your own sound files: Platform notes: • macOS/Linux: .wav or .mp3 files work • Windows: Only .wav files work • If file doesn't exist, falls back to bundled sound Volumes Set per-event volume from to : • = mute, = full volume • Values outside are clamped automatically • On Windows, playback still works but custom volume may not be honored by the default player Custom commands Run your own script when something happens. Use , , , , , and as placeholders: • - Turn command on/off • - Path to your script/executable • - Arguments to pass, can use , , , , , and tokens • - Skip if response was quick, avoids spam (seconds) Example: Log events to a file macOS: Pick your notification style **osascript** (default): Reliable but shows Script Editor icon **node-notifier**: Shows OpenCode icon but might miss notifications sometimes **NOTE:** If you go with node-notifier and start missing notifications, just switch back or remove the option from the config. Users have reported issues with using node-notifier for receiving only sounds and no notification popups. Ghostty notifications If you're using Ghostty terminal, you can use its native notification system via OSC 9 escape sequences: This sends notifications directly through the terminal instead of using system notification tools. Works on any platform where Ghostty is running. Focus detection When is (the default), notifications and sounds are skipped if the terminal running OpenCode is the active/focused window. The idea is simple: if you're already looking at it, you don't need an alert. To disable this and always get notified: Platform support | Platform | Method | Requirements | Status | |----------|--------|--------------|--------| | macOS | AppleScript ( ) | None | Untested | | Linux X11 | | installed | Untested | | Linux Wayland (Hyprland) | | None | Tested | | Linux Wayland (Sway) | | None | Untested | | Linux Wayland (KDE) | | installed | Untested | | Linux Wayland (GNOME) | Not supported | - | Falls back to always notifying | | Linux Wayland (Niri, river, dwl, Cosmic, etc.) | Not supported | - | Falls back to always notifying | | Windows | via PowerShell | None | Untested | **Unsupported compositors**: Wayland has no standard protocol for querying the focused window. Each compositor has its own IPC, and GNOME intentionally doesn't expose focus information. Unsupported compositors fall back to always notifying. **tmux/screen**: When running inside tmux, the tmux server daemonizes and detaches from the terminal's process tree. The plugin handles this by querying the tmux client PID and walking from there. GNU Screen has the same issue but is not currently handled (falls back to always notifying). **Fail-open design**: If detection fails for any reason (missing tools, unknown compositor, permissions), it falls back to always notifying. It never silently eats your notifications. If you test on a platform marked "Untested" and it works (or doesn't), please open an issue and let us know. Linux: Notification Grouping By default, each notification appears as a separate entry. During active sessions this can create noise when multiple events fire quickly (e.g. permission + c…