Skip to content

Opencode Notify

Opencode Notify

Opencode Notify delivers native OS notifications when your OpenCode tasks complete, errors occur, or the AI needs your input. Stay focused on other work and get alerted when the AI finishes or needs attention.

Key Features

Feature	Description
Stay focused	Work in other apps, get notified when the AI needs you
Native OS notifications	macOS Notification Center, Windows Toast, Linux `notify-send`
Smart defaults	Only notifies for meaningful events with quiet-hours support
Terminal focus detection	Suppresses notifications when your terminal is active (macOS)
Click-to-focus	Click notification to foreground terminal (macOS)
37+ terminals supported	Ghostty, Kitty, iTerm2, WezTerm, Alacritty, VS Code, and more

Notification Events

Event	Notifies?	Sound	Why
Session complete	Yes	Glass	Main task done
Session error	Yes	Basso	Something broke
Permission needed	Yes	Submarine	AI is blocked
Question asked	Yes	Submarine	Direct prompts reach you promptly
Sub-task complete/error	No (default)	—	Enable with `notifyChildSessions: true`

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

Installation

Via KDCO Registry (recommended)

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

Or install the full workspace bundle:

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

Manual

Copy plugin files into .opencode/plugins/ preserving the multi-file layout. Requires node-notifier and detect-terminal dependencies.

Configuration

Config file: ~/.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 Options

Key	Default	Description
`notifyChildSessions`	`false`	Include child/sub-session notifications
`terminal`	auto-detected	Override terminal auto-detection
`sounds`	per-event defaults	Per-event sounds (idle, error, permission, question)
`quietHours`	disabled	Scheduled suppression window

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

Links

GitHub Repository — Source code and issues
OCX Monorepo — Contributions and development
Awesome OpenCode — Browse more plugins