opencode-notify

Native OS notifications for OpenCode.

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. Did it finish? Did it error? Is it waiting for permission?

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 - Won't spam you. 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

If you don't have OCX installed, install it from the OCX repository.

Optional: Get everything at once with kdco-workspace:

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

How It Works

"Notify the human when the AI needs them back, not for every micro-event."

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 (click notification → terminal foregrounds)

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 running 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 invocation fails, notifications automatically fall back to the desktop path: alerter on macOS, and the existing node-notifier-backed path on Windows/Linux.

Platform Support

Configuration (Optional)

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

{
  "notifyChildSessions": false,
  "timeout": 0,
  "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).
• timeout (default 0): seconds before a desktop notification disappears automatically. Set to 0 for no timeout. Supported on macOS and Linux outside of cmux.
• 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

FAQ

Does this add bloat to my context?

Minimal footprint. The plugin is event-driven - it listens for session events and fires notifications. No tools are added to your conversation, no prompts are injected beyond initial setup.

Will I get spammed with notifications?

No. Smart defaults prevent noise:

• Only notifies for parent sessions (not every sub-task)
• Supports quiet-hours suppression
• Suppresses when your terminal is the active window on macOS (except direct question notifications)

Can I disable it temporarily?

This plugin does not currently expose an enabled config flag. To disable notifications, remove/uninstall the plugin (for example: ocx remove kdco/notify) and add it back when needed.

Supported Terminals

Uses detect-terminal to automatically identify your terminal. Supports 37+ terminals including:

Ghostty, Kitty, iTerm2, WezTerm, Alacritty, Hyper, Terminal.app, Windows Terminal, VS Code integrated terminal, and many more.

Manual Installation

If you prefer not to use OCX, copy the plugin files into .opencode/plugins/ and preserve the exact multi-file layout shown below:

• .opencode/plugins/notify.ts
• .opencode/plugins/notify/backend.ts
• .opencode/plugins/notify/cmux.ts
• .opencode/plugins/notify/status.ts
• .opencode/plugins/notify/title.ts
• .opencode/plugins/kdco-primitives/index.ts
• .opencode/plugins/kdco-primitives/cmux.ts
• .opencode/plugins/kdco-primitives/get-project-id.ts
• .opencode/plugins/kdco-primitives/log-warn.ts
• .opencode/plugins/kdco-primitives/mutex.ts
• .opencode/plugins/kdco-primitives/shell.ts
• .opencode/plugins/kdco-primitives/temp.ts
• .opencode/plugins/kdco-primitives/terminal-detect.ts
• .opencode/plugins/kdco-primitives/types.ts
• .opencode/plugins/kdco-primitives/with-timeout.ts

Caveats:

• Manually install dependencies (node-notifier, detect-terminal)
• On macOS 13+, install vjeantet/alerter and ensure alerter is on PATH (Homebrew: brew install vjeantet/tap/alerter; MacPorts and GitHub Releases/manual zip are also supported)
• Install cmux if you want the additional cmux-native notification path
• Updates require manual re-copying

Part of the OCX Ecosystem

This plugin is part of the KDCO Registry. For the full experience, check out kdco-workspace which bundles notifications with background agents, specialist agents, and planning tools.

Contributing

This facade is maintained from the main OCX monorepo.

If you want to update opencode-notify itself, start here:

• https://github.com/kdcokenny/ocx/blob/main/workers/kdco-registry/files/plugins/notify.ts

• Open issues here: https://github.com/kdcokenny/ocx/issues/new

• Open pull requests here: https://github.com/kdcokenny/ocx/compare

• Please do not open issues or PRs in this facade repository.

Disclaimer

This project is not built by the OpenCode team and is not affiliated with OpenCode in any way.

License

MIT