opencode-notify

Native OS notifications for OpenCode – know when tasks complete or need your attention.

Stop tab-switching to check if OpenCode is done. Get notified when tasks complete, errors occur, or the AI needs your input.

Features

• Native notifications - Uses notify-send (Linux), terminal-notifier (macOS), or toast (Windows)
• Smart filtering - Only notifies for important events (parent sessions by default)
• Debounced - Won't spam you (5 second cooldown per notification type)
• Focus awareness - Suppresses notifications when your terminal is active (macOS)
• Click-to-focus - Click notification to bring terminal to front (macOS)
• Quiet hours - Configure times to suppress notifications
• Silent operation - Runs in background with zero console output
• Configurable - Customize sounds, behaviors, and filters

Installation

1. Clone this repository

cd ~/repos
git clone https://github.com/yourusername/opencode-notify.git
cd opencode-notify

2. Install dependencies

npm install

3. Install the plugin

npm run install-plugin

This will:

• Copy the plugin to ~/repos/.opencode/plugin/notify.ts
• Create a config at ~/.config/opencode/notify.json
• Update your .opencode/package.json with node-notifier dependency
• Install dependencies if needed

4. Restart OpenCode

The plugin will load automatically on next start.

Usage

Once installed, the plugin runs silently in the background. You'll get notifications when:

• Task completes - "OpenCode is ready for review"
• Error occurs - "OpenCode encountered an error"
• Permission needed - "OpenCode is waiting for you"
• Question asked - "OpenCode has a question"

Test it

After restarting OpenCode:

1. Give OpenCode a task
2. Switch to another window (browser, etc.)
3. You'll get a notification when done!

Configuration

Edit ~/.config/opencode/notify.json:

{
  "enabled": true,
  "notifyChildSessions": false,
  "suppressWhenFocused": true,
  "sounds": {
    "idle": "Glass",
    "error": "Basso",
    "permission": "Submarine",
    "question": "Submarine"
  },
  "quietHours": {
    "enabled": false,
    "start": "22:00",
    "end": "08:00"
  }
}

Options

Option	Default	Description
enabled	true	Enable/disable notifications globally
notifyChildSessions	false	Notify for sub-tasks (can be noisy)
suppressWhenFocused	true	Skip notifications when terminal is active
sounds.idle	"Glass"	Sound when task completes (macOS only)
sounds.error	"Basso"	Sound when error occurs (macOS only)
sounds.permission	"Submarine"	Sound when permission needed (macOS only)
sounds.question	"Submarine"	Sound when question asked (macOS only)
quietHours.enabled	false	Enable quiet hours
quietHours.start	"22:00"	Quiet hours start time (24h format)
quietHours.end	"08:00"	Quiet hours end time (24h format)

Debouncing

The plugin includes automatic debouncing to prevent notification spam:

• 5 second cooldown per notification type
• Each type tracked independently (idle, error, permission, question)
• If multiple events fire rapidly, only the first notifies

Platform Support

Feature	Linux	macOS	Windows
Native notifications	✅	✅	✅
Custom sounds	❌	✅	❌
Focus detection	❌	✅	❌
Click-to-focus	❌	✅	❌
Debouncing	✅	✅	✅

Troubleshooting

Notifications not appearing

1. Check config: Ensure "enabled": true in ~/.config/opencode/notify.json
2. Check plugin loaded: Run opencode debug config and look for notify.ts in the plugin list
3. Test notifications: npm test in this directory
4. Check permissions: Enable notifications for your terminal in system settings
5. Disable Do Not Disturb: Check your system notification settings

Too many/few notifications

• Too many: Set "notifyChildSessions": false (only parent sessions)
• Too few: Set "notifyChildSessions": true (all sessions)
• Terminal focused: Set "suppressWhenFocused": false to always notify

Plugin not loading

# Check if plugin file exists
ls -la ~/repos/.opencode/plugin/notify.ts

# Check if dependencies installed
ls -la ~/repos/.opencode/node_modules/node-notifier

# Reinstall if needed
cd ~/repos/opencode-notify
npm run install-plugin

Uninstallation

rm ~/repos/.opencode/plugin/notify.ts
rm ~/.config/opencode/notify.json

Then restart OpenCode.

Security

This plugin is designed with security and transparency in mind:

• Minimal dependencies - Only node-notifier (10M+ weekly downloads)
• No network calls - Everything runs locally
• No data collection - Your data stays on your machine
• Open source - Full TypeScript source available for audit
• Silent operation - No console spam or logging

Development

Project Structure

opencode-notify/
├── src/
│   ├── index.ts              # Main plugin code
│   └── test-notification.js  # Test script
├── config/
│   └── notify.example.json   # Example config
├── scripts/
│   └── install.js            # Installation script
├── package.json
└── README.md

Testing

# Test notifications work
npm test

# Install plugin locally
npm run install-plugin

# Check plugin loaded
opencode debug config

Credits

Inspired by opencode-notify by Kenny.

This is a clean reimplementation with:

• Debouncing to prevent spam
• Silent operation (no debug logs)
• Simplified installation
• Security-focused design

License

MIT