> ## Documentation Index
> Fetch the complete documentation index at: https://ocx.kdco.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.cmux.dev/)-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](https://www.cmux.dev/)-native path** — When running in [cmux](https://www.cmux.dev/), can route through `cmux notify` and still falls back safely to desktop notifications.

## Installation

```bash theme={null}
ocx add kdco/notify --from https://registry.kdco.dev
```

Or install the full [Workspace bundle](/docs/integrations/workspace):

```bash theme={null}
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`](https://github.com/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](https://www.cmux.dev/)-native path

When OpenCode runs inside [cmux](https://www.cmux.dev/) (with `CMUX_WORKSPACE_ID` set), the plugin can also send notifications via [cmux](https://www.cmux.dev/):

```bash theme={null}
cmux notify --title "..." --subtitle "..." --body "..."
```

If [cmux](https://www.cmux.dev/) 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`:

```json theme={null}
{
  "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](/docs/integrations/workspace) — Full multi-agent workspace bundle.
* [Background Agents](/docs/integrations/background-agents) — Async delegation system.
* [KDCO Workspace Guide](/docs/guides/kdco-workspace) — Installation walkthrough.