Sound Alert

An OpenCode plugin that plays pleasant Windows notification sounds whenever the AI is waiting for your input — so you can stay focused on other things and come back when it's your turn.

---

Why

When OpenCode is running a long task, it's easy to miss the moment it finishes and needs your attention. This plugin listens to OpenCode's event bus and plays a soft notification sound — similar to GitHub Copilot's tone — so you always know when to look back at the terminal.

Sounds

Uses native Windows WAV files via System.Media.SoundPlayer. No third-party dependencies.

Event	Sound file	When it plays
session.idle	Windows Notify System Generic.wav	AI finished a task or asked a question
permission.asked	Windows Notify Messaging.wav	AI needs your approval to run an action
session.error	Windows Notify.wav	Something went wrong in the session

Falls back to a dual-tone [console]::beep (ding-dong) if WAV playback is unavailable.

---

Requirements

• OpenCode >= 1.4
• Windows 10 or 11
• PowerShell (built-in on Windows)
• Bun >= 1.0 (OpenCode's runtime)

---

Installation

Option 1 — Manual (recommended for now)

Copy src/index.ts into your OpenCode global plugins directory:

# Run this in the repository root
Copy-Item src\index.ts "$env:USERPROFILE\.config\opencode\plugins\opencode-sound-alert.ts"

Restart OpenCode. That's it — plugins in ~/.config/opencode/plugins/ are loaded automatically.

Option 2 — npm / bun (once published)

bun add -g opencode-sound-alert
# or
npm install -g opencode-sound-alert

Then add it to your ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-sound-alert"]
}

---

Verifying the Installation

Inside OpenCode, run:

/status

You should see opencode-sound-alert listed under active plugins.

---

Customizing Sounds

Edit the WAV_FILE_MAP in src/index.ts:

const WAV_FILE_MAP: Record<SoundType, string> = {
  idle:       "Windows Notify System Generic.wav",
  permission: "Windows Notify Messaging.wav",
  error:      "Windows Notify.wav",
};

Any .wav file in %WINDIR%\Media\ works. Popular options:

File	Character
Windows Notify System Generic.wav	Soft ding-dong (default idle)
Windows Notify Messaging.wav	Friendly ping
Windows Notify Calendar.wav	Clean reminder tone
chimes.wav	Classic chimes
tada.wav	Upbeat celebration

---

Testing Sounds Without Restarting OpenCode

$play = { param($f) (New-Object Media.SoundPlayer "$env:WINDIR\Media\$f").PlaySync() }
& $play "Windows Notify System Generic.wav"
Start-Sleep -Milliseconds 600
& $play "Windows Notify Messaging.wav"
Start-Sleep -Milliseconds 600
& $play "Windows Notify.wav"

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Particularly interested in:

• 🍎 macOS support via afplay
• 🐧 Linux support via paplay / aplay
• 🔊 Custom sound files bundled with the package

---

Changelog

See CHANGELOG.md.

---

License

MIT