OpenCode Win Notification Plugin

Windows sound notifications for OpenCode. This plugin plays a sound when OpenCode finishes a task and the session enters session.idle.

By default, it uses the Windows system notification sound. If you prefer, you can configure it to play your own .wav file instead.

Installation

1. Copy win_notif.js into the following directory:

C:\Users\YOUR_USERNAME\.config\opencode\plugins\

2. Restart OpenCode to activate the plugin.

Configuration

Edit the CONFIG block at the top of win_notif.js.

const CONFIG = {
	// Set to false to play the default Windows system sound.
	// Set to true to play a custom .wav file.
	useCustomSound: false,

	// Required only when useCustomSound is true.
	// Use double backslashes (\\) in Windows file paths.
	customSoundPath: "C:\\sound\\finish.wav",
};

Behavior:

• useCustomSound: false plays the default Windows notification sound.
• useCustomSound: true plays the .wav file defined in customSoundPath.

Important: Windows paths must use double backslashes (\\).

Troubleshooting

• Sound format: Renaming a file to .wav is not enough. The file must be a real PCM-encoded .wav file. If it is only renamed, PowerShell MediaPlayer may fail silently.

• File path: If you do not hear anything, check your volume level and confirm that customSoundPath points to a valid file.

• Manual test tip: To verify that the sound file and path are valid, users can run this command directly in the terminal:

   powershell -c "$m = New-Object -ComObject WMPlayer.OCX; $m.URL = 'C:\sound\finish.wav'; $m.controls.play(); start-sleep -s 5"

• Logs: OpenCode should print [win-notif] Session finished, triggering sound... in the terminal when the sound is triggered. If you do not see this message, the plugin may not be loading or the session.idle event may not be firing.

• Developer note: OpenCode uses the Bun Shell API. When writing PowerShell variables such as $m, escape the dollar sign so Bun does not treat it as a JavaScript template literal value. Use \$m, not $m.

Author

Furkan Demircan