@serkanalgur/opencodev2-notification

Native OS notifications for OpenCode V2

A CLI plugin for OpenCode V2 that delivers native OS notifications when tasks complete, errors occur, or the AI needs your input.

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.
• Uses OpenCode's built-in attention API - Native notifications on all platforms
• Smart defaults - Won't spam you. Only notifies for meaningful events with parent-session filtering and quiet-hours support.
• Lightweight - Event-driven, no tools added to your conversation

Installation

opencode plugin add @serkanalgur/opencodev2-notification

Via opencode.json

Add to your opencode.json or opencode.jsonc:

{
  "plugins": ["@serkanalgur/opencodev2-notification"]
}

As a local plugin

Or copy the plugin files to your .opencode/plugins/ directory:

.opencode/plugins/notification/index.ts

⚠️ Required: enable attention (mandatory)

This plugin will NOT work unless you turn on OpenCode's attention setting first. The plugin only uses OpenCode's built-in notification API — it cannot enable it for you. If attention is off, every notification is silently dropped (attention_disabled) and nothing appears on screen or plays a sound.

Add this block to ~/.config/opencode/cli.json:

{
  "attention": {
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

• attention.notifications → shows system notifications (usually when the terminal is not focused).
• attention.sound → plays a sound always (even while the terminal is focused).

On macOS, also allow notifications for your terminal app: System Settings → Notifications → (Terminal/iTerm) → Allow Notifications.

If attention is disabled, v1.2.6+ prints a clear warning in the terminal when an event fires:

opencodev2-notification: attention is disabled. Enable it in ~/.config/opencode/cli.json:
  "attention": { "notifications": true, "sound": true }

How It Works

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

| Event | Notifies? | Sound | Why | |-------|-----------|-------|-----| | Session complete | Yes | done | Main task done - time to review | | Session error | Yes | error | Something broke - needs attention | | Permission needed | Yes | permission | AI is blocked, waiting for you | | Sub-task complete/error | No (default) | - | Set notifyChildSessions: true to include child sessions |

The plugin automatically:

1. Uses OpenCode's built-in attention.notify() API for native notifications
2. Only notifies when terminal is not focused (no spam while you're working)
3. Deduplicates rapid-fire notifications

Platform Support

| Platform | Method | Status | |----------|--------|--------| | macOS | Notification Center | ✅ Full support | | Windows | Toast notifications | ✅ Full support | | Linux | Desktop notifications | ✅ Full support |

Plugin Configuration (Optional)

The plugin ships with sensible defaults and works right after you've completed the required attention setup above.

To customize the plugin itself, create ~/.config/opencode/opencodev2-notification.json:

{
  "notifyChildSessions": false,
  "sounds": {
    "idle": "done",
    "error": "error",
    "permission": "permission"
  },
  "quietHours": {
    "enabled": false,
    "start": "22:00",
    "end": "08:00"
  }
}

Configuration Keys

| Key | Type | Default | Description | |-----|------|---------|-------------| | notifyChildSessions | boolean | false | Include child/sub-session notifications | | sounds.idle | string | "done" | Sound for session complete | | sounds.error | string | "error" | Sound for errors | | sounds.permission | string | "permission" | Sound for permission requests | | quietHours.enabled | boolean | false | Enable quiet hours | | quietHours.start | string | "22:00" | Quiet hours start (HH:MM) | | quietHours.end | string | "08:00" | Quiet hours end (HH:MM) |

Available Sound Names

default, question, permission, error, done, subagent_done

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.

Will I get spammed with notifications?

No. Smart defaults prevent noise:

• Only notifies for parent sessions (not every sub-task)
• Supports quiet-hours suppression
• Only notifies when terminal is not focused
• Deduplication prevents rapid-fire notifications

Can I disable it temporarily?

Remove the plugin from your opencode.json or delete the plugin files.

Credits

Inspired by opencode-notify by kdcokenny.

License

MIT