@aungmyokyaw/opencode-notify

Get notified when OpenCode AI sessions complete. Zero-config defaults, multi-platform support, and webhook integration.

Quick Start

Add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@aungmyokyaw/opencode-notify"]
}

Done. OpenCode installs and loads the plugin automatically. You'll get a terminal bell on every session completion.

Install

Via npm (recommended)

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@aungmyokyaw/opencode-notify"]
}

OpenCode installs npm plugins automatically at startup using Bun.

From local files

Clone or download this repo, then point to the built file:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///absolute/path/to/opencode-notify/dist/plugin.js"]
}

Or copy dist/plugin.js into your plugin directory:

• Project-level: .opencode/plugins/
• Global: ~/.config/opencode/plugins/

Why This Plugin?

| Feature | @aungmyokyaw/opencode-notify | opencode-notification | @goodnesshq/opencode-notification | |---------|-------------------------------|-------------------------|-------------------------------------| | Install method | npm auto-install | npm auto-install | npx setup required | | macOS notifications | ✅ | ✅ | ✅ | | Terminal bell | ✅ | ✅ | ❌ | | TUI popup | ✅ | ❌ | ❌ | | Custom webhook | ✅ | ❌ | ❌ | | Config location | opencode.json | opencode.json | External JSON file | | Zero-config default | ✅ | ❌ | ❌ | | Events supported | session.idle | 3 events | 3+ events |

Best for: Users who want simple, configurable notifications without external setup commands or config files.

Config

Add a plugin-notify block to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@aungmyokyaw/opencode-notify"],
  "plugin-notify": {
    "enabled": true,
    "notifiers": ["macos", "bell"],
    "macos": { "sound": "default" },
    "bell": { "count": 1 },
    "tui": { "durationMs": 5000 },
    "webhook": {
      "url": "https://hooks.slack.com/...",
      "method": "POST",
      "headers": {}
    },
    "dnd": false,
    "focusAware": false
  }
}

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Turn notifications on/off | | notifiers | string[] | [] | List of notifiers to use | | dnd | boolean | false | Do-not-disturb mode (silences all) | | focusAware | boolean | false | Skip notifications when OpenCode has focus | | macos.sound | string | — | macOS alert sound name | | bell.count | number | 1 | Number of bell characters | | tui.durationMs | number | 5000 | How long TUI popup stays visible | | webhook.url | string | — | POST destination URL | | webhook.method | string | POST | HTTP method | | webhook.headers | object | {} | Extra request headers |

Notifiers

macos

Native macOS notification via osascript.

{
  "plugin-notify": {
    "notifiers": ["macos"],
    "macos": { "sound": "Purr" }
  }
}

Requirements: macOS with osascript available.

bell

Terminal bell character (\u0007). Works on every platform.

{
  "plugin-notify": {
    "notifiers": ["bell"],
    "bell": { "count": 3 }
  }
}

tui

Boxed popup drawn directly in the terminal.

{
  "plugin-notify": {
    "notifiers": ["tui"],
    "tui": { "durationMs": 3000 }
  }
}

Output looks like:

┌─────────────────────────────┐
│  Session Complete: My Task  │
│  Summary: Done              │
└─────────────────────────────┘

webhook

POST JSON payload to any URL.

{
  "plugin-notify": {
    "notifiers": ["webhook"],
    "webhook": {
      "url": "https://hooks.slack.com/services/...",
      "method": "POST",
      "headers": { "Authorization": "Bearer xxx" }
    }
  }
}

Payload shape:

{
  "event": "session.idle",
  "title": "OpenCode",
  "summary": "Session complete",
  "timestamp": "2026-04-20T00:00:00.000Z"
}

Events

The plugin listens for OpenCode events and dispatches notifications.

| Event | When it fires | Default action | |-------|--------------|----------------| | session.idle | AI finishes responding | ✅ Notify | | session.error | Session encounters an error | ❌ (not yet) | | permission.asked | LLM needs your permission | ❌ (not yet) |

Note: Currently only session.idle is implemented. session.error and permission.asked are planned for v0.2.0.

How It Works

1. OpenCode fires session.idle when the AI stops generating.
2. Plugin checks enabled and dnd flags.
3. If focusAware is on and OpenCode has terminal focus, skip.
4. Build NotifyPayload from event data.
5. Dispatch to every notifier in the notifiers array.
6. Each notifier runs independently. Failures are logged to stderr but never block the session.

Troubleshooting

macOS notifications not showing

• Verify osascript is in your PATH: which osascript
• Check macOS Notification Center settings for "Script Editor"
• Try a manual test: osascript -e 'display notification "test"'

Webhook not firing

• Verify url is set in config
• Check network connectivity: curl -I your-webhook-url
• Look for Webhook URL not configured or Webhook failed in OpenCode output

Plugin not loading

• Verify plugin is in opencode.json plugin array
• Check OpenCode startup logs for install errors
• Try local file path instead of npm name to rule out registry issues

Too many notifications

• Enable dnd: true for focused work sessions
• Enable focusAware: true to skip when OpenCode is active
• Reduce bell.count to 1

Contributing

PRs welcome. See CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history.

License

MIT