Notify Plugin

Native OS notifications for OpenCode — know when your AI needs you back

Overview

A plugin for OpenCode that delivers Native OS notifications when tasks complete, errors occur, or the AI needs your input. It uses native OS notification delivery on macOS, Windows, and Linux, with an additional cmux-native path when available.

Why This Exists

You delegate a task and switch to another window. Now you’re checking back every 30 seconds. This plugin solves that:

• Stay focused — Work in other apps. A notification arrives when the AI needs you.
• Native OS notifications first — Uses macOS Notification Center via alerter, plus Windows Toast and Linux notify-send via node-notifier.
• Smart defaults — Only notifies for meaningful events, with parent-session filtering and quiet-hours support.
• Additional cmux-native path — When running in cmux, can route through cmux notify and still falls back safely to desktop notifications.

Installation

ocx add kdco/notify --from https://registry.kdco.dev

Or install the full Workspace bundle:

ocx add kdco/workspace --from https://registry.kdco.dev

Notification Events

Event	Notifies?	Sound	Why
Session complete	Yes	Glass	Main task done — time to review
Session error	Yes	Basso	Something broke — needs attention
Permission needed	Yes	Submarine	AI is blocked, waiting for you
Question asked	Yes	Submarine (default)	Questions should always reach you promptly
Sub-task complete / error	No (default)	—	Set notifyChildSessions: true to include child-session session.idle and session.error events

The plugin automatically:

1. Detects your terminal emulator (supports 37+ terminals)
2. Suppresses session.idle, session.error, and permission.updated notifications when your terminal is focused on macOS
3. Enables click-to-focus on macOS

Question notifications intentionally bypass macOS focus suppression so direct prompts are not missed.

Native OS Notification Paths

By default, notifications go through the native OS desktop notification path:

• macOS: Notification Center via vjeantet/alerter (alerter must be on PATH, macOS 13+)
• Windows: Toast notifications (SnoreToast backend)
• Linux: notify-send

macOS desktop fallback requires installing alerter separately. Supported install paths include Homebrew (brew install vjeantet/tap/alerter), MacPorts, or downloading the release zip from GitHub Releases and placing the binary on PATH.

Additional cmux-native path

When OpenCode runs inside cmux (with CMUX_WORKSPACE_ID set), the plugin can also send notifications via cmux:

cmux notify --title "..." --subtitle "..." --body "..."

If cmux is unavailable or notification delivery fails, the plugin automatically falls back to the desktop path: alerter on macOS, and the existing node-notifier-backed path on Windows/Linux.

Platform Support

Feature	macOS	Windows	Linux
Native OS notifications	Yes	Yes	Yes
Custom sounds	Yes	No	No
Focus detection	Yes	No	No
Click-to-focus	Yes	No	No
Terminal detection	Yes	Yes	Yes

Configuration (Optional)

Works out of the box. To customize, create ~/.config/opencode/kdco-notify.json:

{
  "notifyChildSessions": false,
  "terminal": "ghostty",
  "sounds": {
    "idle": "Glass",
    "error": "Basso",
    "permission": "Submarine",
    "question": "Submarine"
  },
  "quietHours": {
    "enabled": false,
    "start": "22:00",
    "end": "08:00"
  }
}

Configuration keys:

• notifyChildSessions (default false) — when true, include child/sub-session session.idle and session.error notifications (question and permission notifications are unaffected).
• terminal (optional) — override terminal auto-detection.
• sounds — per-event sounds (idle, error, permission, optional question).
• quietHours — scheduled suppression window.

Available macOS sounds: Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink

See Also

• Workspace Integration — Full multi-agent workspace bundle.
• Background Agents — Async delegation system.
• KDCO Workspace Guide — Installation walkthrough.