opencode-notify

System popups with actionable buttons for Opencode. When Opencode needs permission or has a question, you'll receive a popup you can respond to directly – no need to switch back to the terminal.

Features

• Actionable buttons – Accept, Always, Reject, or Dismiss permission requests directly from popups
• Cross-platform – Works on macOS (no dependencies), Linux, and Windows
• Terminal focus detection – Suppresses popups when your terminal is already focused
• Quiet hours – Optionally silence alerts during specified times
• Child session control – Choose whether to notify for subagent sessions
• Auto-focus – Optionally focus your terminal after responding to a popup
• Idle alerts – Optionally alert when the agent stops without requesting input

Installation

Add the plugin to your Opencode configuration file (~/.config/opencode/config.json):

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

The plugin is installed automatically via Bun at startup.

Platform Dependencies

macOS

No additional dependencies. The plugin bundles a Swift app that displays notifications.

By default, the plugin uses native macOS Notification Centre banners. These appear in Notification Centre, respect Do Not Disturb, and show the app name as "OpenCode Request".

Optionally, set nativeMacNotifications: false to use modal alert dialogs instead. Modal dialogs support multiple action buttons (Accept/Always/Reject) and bypass Do Not Disturb, but don't appear in Notification Centre.

Linux

For action button support, install D-Bus development libraries:

# Debian/Ubuntu
sudo apt install libdbus-1-dev

# Fedora
sudo dnf install dbus-devel

The plugin will fall back to notify-send if D-Bus isn't available, but actions won't work.

Windows

Requires Windows 10 version 1709 or later. No additional dependencies needed.

Configuration

Create ~/.config/opencode/opencode-notify.json:

{
  "sounds": {
    "permission": "Submarine",
    "error": "Basso"
  },
  "quietHours": {
    "enabled": false,
    "start": "22:00",
    "end": "08:00"
  },
  "notifyChildSessions": false,
  "terminal": null,
  "focusAfterAction": true,
  "notifyOnIdle": false,
  "nativeMacNotifications": true
}

Options

Option	Type	Default	Description
sounds.permission	string	"Submarine"	Sound for permission requests and questions
sounds.error	string	"Basso"	Sound for errors
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)
notifyChildSessions	boolean	false	Notify for subagent sessions
terminal	string | null	null	Override terminal detection
focusAfterAction	boolean	true	Focus terminal after responding to a popup
notifyOnIdle	boolean	false	Notify when the agent stops without requesting input
nativeMacNotifications	boolean	true	Use macOS Notification Centre instead of modal dialogs (macOS only)

Terminal Detection

The plugin auto-detects these terminals:

• Ghostty
• Kitty
• iTerm2
• WezTerm
• Apple Terminal
• Alacritty
• Hyper
• Windows Terminal

Set terminal in config to override if detection fails.

How It Works

The plugin hooks into Opencode events:

1. Permission requests → Shows popup with Accept/Always/Reject/Dismiss buttons
2. Questions → Shows popup when Opencode asks a question (AskUserQuestion tool) with View/Dismiss buttons
3. Session errors → Shows error popup
4. Session idle → Optionally shows popup when the agent stops without requesting input (disabled by default, enable with notifyOnIdle). Only fires once per idle period – resets when the agent becomes active again.

When you click a button on a permission popup, the plugin:

1. Sends your response to Opencode via its API
2. Focuses your terminal window (if focusAfterAction is enabled)

Comparison with Similar Plugins

Feature	mohak34/opencode-notifier	This Plugin
Action buttons	No	Yes
macOS notifications	osascript	CFUserNotification or Notification Centre
Linux notifications	notify-send	D-Bus
Windows notifications	node-notifier	powertoast
Permission response	Manual in terminal	Click button
Terminal focus detection	No	Yes

Development

# Install dependencies
bun install

# Run tests
bun test

# Type check
bun run typecheck

# Build
bun run build

Licence

MIT