Native macOS notifications and sounds for OpenCode - zero dependencies
npm install opencode-notification-macosNative macOS notifications and sounds for OpenCode - zero external dependencies.


š Native macOS Notifications - Uses osascript for system notifications
š System Sounds - Uses afplay with all 14 built-in macOS sounds
āļø Configurable - Per-event sound customization
š Dual Config - Global + project-level configuration
šÆ Zero Dependencies - No external libraries, just native macOS commands
If you're an AI agent setting this up for a user, run these commands:
``bash1. Install the plugin globally
npm install -g opencode-notification-macos
$3
`bash
npm install -g opencode-notification-macos
`Then add to your
~/.config/opencode/opencode.jsonc:`json
{
"plugin": [
"opencode-notification-macos"
]
}
`Configuration
$3
`bash
Configure sounds interactively
npx opencode-notification-macos configList available sounds
npx opencode-notification-macos listPreview a sound
npx opencode-notification-macos previewShow current configuration
npx opencode-notification-macos showReset to defaults
npx opencode-notification-macos reset
`$3
The plugin supports two configuration locations (project config overrides global):
Global (applies to all projects):
`
~/.config/opencode/opencode-notification-macos.json
`Project (applies to specific project):
`
.opencode/notification.json
`$3
`json
{
"sound": true,
"notification": true,
"showProjectName": true,
"events": {
"complete": { "sound": true, "notification": true },
"error": { "sound": true, "notification": true },
"question": { "sound": true, "notification": true },
"permission": { "sound": true, "notification": true },
"subagent_complete": { "sound": false, "notification": false }
},
"messages": {
"complete": "ā
Task completed",
"error": "ā Error occurred",
"question": "ā OpenCode needs your input",
"permission": "š Permission required",
"subagent_complete": "Subagent finished"
},
"sounds": {
"complete": "Glass",
"error": "Basso",
"question": "Ping",
"permission": "Tink",
"subagent_complete": "Pop"
}
}
`$3
All 14 macOS system sounds are available:
-
Basso - Low alert sound
- Blow - Airy whoosh
- Bottle - Cork pop
- Frog - Frog croak
- Funk - Funk guitar riff
- Glass - Glass tap (default for completion)
- Hero - Heroic fanfare
- Morse - Morse code beeps
- Ping - Simple ping (default for questions)
- Pop - Pop sound
- Purr - Cat purr
- Sosumi - Classic Mac sound
- Submarine - Sonar ping
- Tink - Light bell (default for permissions)Events
The plugin triggers on these OpenCode events:
| Event | Description | Default Sound |
|-------|-------------|---------------|
|
complete | Main task finished | Glass |
| error | An error occurred | Basso |
| question | OpenCode needs input | Ping |
| permission | Permission required | Tink |
| subagent_complete | Background task finished | Pop |AI Agent Setup Instructions
If you are an AI assistant reading this to set up the plugin for a user, follow these exact steps:
$3
`bash
Verify macOS
sw_vers -productNameVerify OpenCode is installed
which opencode
`$3
`bash
npm install -g opencode-notification-macos
`$3
Option A - Interactive (recommended):
`bash
npx opencode-notification-macos config
`Option B - Create config file directly:
`bash
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/opencode-notification-macos.json << 'EOF'
{
"sound": true,
"notification": true,
"showProjectName": true,
"sounds": {
"complete": "Glass",
"error": "Basso",
"question": "Ping",
"permission": "Tink",
"subagent_complete": "Pop"
}
}
EOF
`$3
`bash
Read current config
cat ~/.config/opencode/opencode.jsoncAdd plugin to the plugin array
If opencode.jsonc exists, add "opencode-notification-macos" to the plugin array
If it doesn't exist, create it with the plugin
`$3
`bash
Test sound
npx opencode-notification-macos previewTest with OpenCode
opencode "say hello and wait for my response"
`Troubleshooting
$3
1. Check system volume:
`bash
afplay /System/Library/Sounds/Glass.aiff
`2. Check notification permissions:
- System Settings ā Notifications ā Script Editor
- Ensure notifications are enabled
3. Verify config:
`bash
npx opencode-notification-macos show
`$3
1. Check OpenCode config syntax:
`bash
cat ~/.config/opencode/opencode.jsonc
`2. Clear OpenCode cache:
`bash
rm -rf ~/.cache/opencode
`3. Restart OpenCode
$3
The plugin uses
osascript for notifications. Grant permissions:
- System Settings ā Privacy & Security ā Automation
- Ensure your terminal has permission to control System EventsDevelopment
`bash
Clone repository
git clone https://github.com/evanstinger/opencode-notification-macos.git
cd opencode-notification-macosInstall dependencies
npm installBuild
npm run buildWatch mode
npm run devType check
npm run typecheck
`How It Works
This plugin replaces external notification libraries with native macOS commands:
- Sounds: Uses
afplay (built into macOS) to play system sounds from /System/Library/Sounds/
- Notifications: Uses osascript` (AppleScript) to display native macOS notificationsMIT Ā© Evan Stinger
Contributions welcome! Please read the contributing guide first.
- OpenCode - The AI coding agent
- @mohak34/opencode-notifier - Cross-platform notifier (uses node-notifier)