@mohak34/opencode-notifier 0.1.19 → 0.1.20-beta.0

package/README.md

@@ -2,9 +2,9 @@
 
 OpenCode plugin that plays sounds and sends system notifications when permission is needed, generation completes, errors occur, or the question tool is invoked. Works on macOS, Linux, and Windows.
 
-## Installation
+## Quick Start
 
-Add the plugin to your `opencode.json` or `opencode.jsonc`:
+Add this to your `opencode.json`:
 
 ```json
 {
@@ -12,99 +12,39 @@ Add the plugin to your `opencode.json` or `opencode.jsonc`:
 }
 ```
 
-Using `@latest` ensures you always get the newest version when the cache is refreshed.
+Restart OpenCode. Done.
 
-To pin a specific version:
+## What it does
 
-```json
-{
-  "plugin": ["@mohak34/opencode-notifier@0.1.14"]
-}
-```
+You'll get notified when:
+- OpenCode needs permission to run something
+- Your session finishes
+- An error happens  
+- The question tool pops up
 
-Restart OpenCode. The plugin will be automatically installed and loaded.
+There's also `subagent_complete` for when subagents finish, but that's silent by default so you don't get spammed.
 
-## Updating
-
-OpenCode caches plugins in `~/.cache/opencode`. Plugins are not auto-updated; you need to clear the cache to get new versions.
+## Setup by platform
 
-### If you use `@latest`
+**macOS**: Nothing to do, works out of the box. Shows the Script Editor icon.
 
-Clear the cache and restart OpenCode:
-
-**Linux/macOS:**
+**Linux**: Should work if you already have a notification system setup. If not install libnotify:
 
 ```bash
-rm -rf ~/.cache/opencode/node_modules/@mohak34/opencode-notifier
+sudo apt install libnotify-bin  # Ubuntu/Debian
+sudo dnf install libnotify       # Fedora  
+sudo pacman -S libnotify         # Arch
 ```
 
-**Windows (PowerShell):**
-
-```powershell
-Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\node_modules\@mohak34\opencode-notifier"
-```
-
-Then restart OpenCode - it will download the latest version automatically.
-
-### If you use a pinned version (e.g., `@0.1.14`)
-
-1. Update the version in your `opencode.json`:
-
-   ```json
-   {
-     "plugin": ["@mohak34/opencode-notifier@0.1.14"]
-   }
-   ```
-
-2. Clear the cache (see commands above)
-
-3. Restart OpenCode
-
-### Check installed version
-
-**Linux/macOS:**
-
-```bash
-cat ~/.cache/opencode/node_modules/@mohak34/opencode-notifier/package.json | grep version
-```
-
-**Windows (PowerShell):**
-
-```powershell
-Get-Content "$env:USERPROFILE\.cache\opencode\node_modules\@mohak34\opencode-notifier\package.json" | Select-String "version"
-```
-
-## Platform Notes
-
-The plugin works out of the box on all platforms. For best results:
-
-- **macOS**: No additional setup required. Notifications display the Script Editor icon (custom icons not supported with osascript for reliability)
-- **Windows**: No additional setup required. The OpenCode icon displays in notifications
-- **Linux**: For sounds, one of these should be installed: `paplay`, `aplay`, `mpv`, or `ffplay`. For notifications, `notify-send` is recommended. The OpenCode icon displays in notifications
-
-**Note**: To disable icons, set `showIcon: false` in your configuration.
-
-### macOS: Choosing Your Notification System
-
-On macOS, you can choose between two notification backends:
+For sounds, you need one of: `paplay`, `aplay`, `mpv`, or `ffplay`
 
-- **`osascript`** (default): Most reliable method that always works. Uses AppleScript to display notifications. **Limitation**: Cannot display custom icons (shows Script Editor icon instead).
+**Windows**: Works out of the box. But heads up:
+- Only `.wav` files work (not mp3)
+- Use full paths like `C:/Users/You/sounds/alert.wav` not `~/`
 
-- **`node-notifier`**: Supports custom icons but some users experience reliability issues where notifications don't appear.
+## Config file
 
-To use `node-notifier` with custom icons:
-
-```json
-{
-  "notificationSystem": "node-notifier"
-}
-```
-
-If you experience missing notifications with `node-notifier`, switch back to `osascript` (or remove the option to use the default).
-
-## Configuration
-
-To customize the plugin, create `~/.config/opencode/opencode-notifier.json`:
+Create `~/.config/opencode/opencode-notifier.json` with the defaults:
 
 ```json
 {
@@ -135,204 +75,267 @@ To customize the plugin, create `~/.config/opencode/opencode-notifier.json`:
     "question": "Session has a question"
   },
   "sounds": {
-    "permission": "/path/to/custom/sound.wav",
-    "complete": "/path/to/custom/sound.wav",
-    "subagent_complete": "/path/to/custom/sound.wav",
-    "error": "/path/to/custom/sound.wav",
-    "question": "/path/to/custom/sound.wav"
+    "permission": null,
+    "complete": null,
+    "subagent_complete": null,
+    "error": null,
+    "question": null
+  },
+  "volumes": {
+    "permission": 1,
+    "complete": 1,
+    "subagent_complete": 1,
+    "error": 1,
+    "question": 1
   }
 }
 ```
 
-### Options
+## All options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `sound` | boolean | `true` | Global toggle for all sounds |
-| `notification` | boolean | `true` | Global toggle for all notifications |
-| `timeout` | number | `5` | Notification duration in seconds (Linux only) |
-| `showProjectName` | boolean | `true` | Show project folder name in notification title |
-| `showIcon` | boolean | `true` | Show OpenCode icon in notifications |
-| `notificationSystem` | string | `"osascript"` | macOS only: `"osascript"` (reliable, no icons) or `"node-notifier"` (icons, may have issues) |
-| `command` | object | — | Command execution settings (enabled/path/args/minDuration) |
+### Global options
+
+```json
+{
+  "sound": true,
+  "notification": true,
+  "timeout": 5,
+  "showProjectName": true,
+  "showIcon": true,
+  "notificationSystem": "osascript"
+}
+```
+
+- `sound` - Turn sounds on/off (default: true)
+- `notification` - Turn notifications on/off (default: true)
+- `timeout` - How long notifications show in seconds, Linux only (default: 5)
+- `showProjectName` - Show folder name in notification title (default: true)
+- `showIcon` - Show OpenCode icon, Windows/Linux only (default: true)
+- `notificationSystem` - macOS only: `"osascript"` or `"node-notifier"` (default: "osascript")
 
 ### Events
 
-Control sound and notification separately for each event:
+Control each event separately:
 
 ```json
 {
   "events": {
     "permission": { "sound": true, "notification": true },
-    "complete": { "sound": false, "notification": true },
-    "subagent_complete": { "sound": true, "notification": false },
-    "error": { "sound": true, "notification": false },
+    "complete": { "sound": true, "notification": true },
+    "subagent_complete": { "sound": false, "notification": false },
+    "error": { "sound": true, "notification": true },
     "question": { "sound": true, "notification": true }
   }
 }
 ```
 
-Or use a boolean to toggle both:
+Or use true/false for both:
 
 ```json
 {
   "events": {
-    "permission": true,
-    "complete": false,
-    "subagent_complete": true,
-    "error": true,
-    "question": true
+    "complete": false
   }
 }
 ```
 
-Note: `complete` fires for primary (main) session completion, while `subagent_complete` fires for subagent completion. `subagent_complete` defaults to disabled (both sound and notification are false).
-
 ### Messages
 
-Customize notification text:
+Customize the notification text:
 
 ```json
 {
   "messages": {
-    "permission": "Action required",
-    "complete": "Done!",
-    "subagent_complete": "Subagent finished",
-    "error": "Something went wrong",
-    "question": "Input needed"
+    "permission": "Session needs permission",
+    "complete": "Session has finished",
+    "subagent_complete": "Subagent task completed",
+    "error": "Session encountered an error",
+    "question": "Session has a question"
   }
 }
 ```
 
-### Command
-
-Run a custom command when events fire. Use `{event}` and `{message}` tokens in `path` or `args` to inject the event name and message.
+### Sounds
 
-`command.minDuration` (optional, seconds) gates command execution based on the time elapsed since the last user prompt.
-- Applies to all events for the custom command.
-- If elapsed time is known and is below `minDuration`, the command is skipped.
-- If elapsed time cannot be determined for an event, the command still runs.
+Use your own sound files:
 
 ```json
 {
-  "command": {
-    "enabled": true,
-    "path": "/path/to/command",
-    "args": ["--event", "{event}", "--message", "{message}"],
-    "minDuration": 10
+  "sounds": {
+    "permission": "/path/to/alert.wav",
+    "complete": "/path/to/done.wav",
+    "subagent_complete": "/path/to/subagent-done.wav",
+    "error": "/path/to/error.wav",
+    "question": "/path/to/question.wav"
   }
 }
 ```
 
-### Custom Sounds
+Platform notes:
+- macOS/Linux: .wav or .mp3 files work
+- Windows: Only .wav files work
+- If file doesn't exist, falls back to bundled sound
 
-Use your own sound files:
+### Volumes
+
+Set per-event volume from `0` to `1`:
 
 ```json
 {
-  "sounds": {
-    "permission": "/home/user/sounds/alert.wav",
-    "complete": "/home/user/sounds/done.wav",
-    "subagent_complete": "/home/user/sounds/subagent-done.wav",
-    "error": "/home/user/sounds/error.wav",
-    "question": "/home/user/sounds/question.wav"
+  "volumes": {
+    "permission": 0.6,
+    "complete": 0.3,
+    "subagent_complete": 0.15,
+    "error": 1,
+    "question": 0.7
   }
 }
 ```
 
-If a custom sound file path is provided but the file doesn't exist, the plugin will fall back to the bundled sound.
+- `0` = mute, `1` = full volume
+- Values outside `0..1` are clamped automatically
+- On Windows, playback still works but custom volume may not be honored by the default player
 
-### Example: Different behaviors for main and subagent completion
+### Custom commands
 
-You may want different notification behaviors for primary sessions versus subagent sessions. For example:
+Run your own script when something happens. Use `{event}` and `{message}` as placeholders:
 
-- **Main session completion**: Play a sound and show a system notification
-- **Subagent completion**: Play a different sound, but no system notification
+```json
+{
+  "command": {
+    "enabled": true,
+    "path": "/path/to/your/script",
+    "args": ["{event}", "{message}"],
+    "minDuration": 10
+  }
+}
+```
+
+- `enabled` - Turn command on/off
+- `path` - Path to your script/executable
+- `args` - Arguments to pass, can use `{event}` and `{message}` tokens
+- `minDuration` - Skip if response was quick, avoids spam (seconds)
+
+#### Example: Log events to a file
 
 ```json
 {
-  "events": {
-    "complete": { "sound": true, "notification": true },
-    "subagent_complete": { "sound": true, "notification": false }
-  },
-  "messages": {
-    "complete": "Session has finished",
-    "subagent_complete": "Subagent task completed"
-  },
-  "sounds": {
-    "complete": "/home/user/sounds/main-done.wav",
-    "subagent_complete": "/home/user/sounds/subagent-chime.wav"
+  "command": {
+    "enabled": true,
+    "path": "/bin/bash",
+    "args": [
+      "-c",
+      "echo '[{event}] {message}' >> /tmp/opencode.log"
+    ]
   }
 }
 ```
 
-## Troubleshooting
+## macOS: Pick your notification style
 
-### macOS: Notifications not showing (only sound works)
+**osascript** (default): Reliable but shows Script Editor icon
 
-**Update to v0.1.10 or later** - this version includes a fix for macOS notification events.
+```json
+{ 
+  "notificationSystem": "osascript" 
+}
+```
 
-If notifications still don't work after updating:
+**node-notifier**: Shows OpenCode icon but might miss notifications sometimes
 
-1. **Check notification permissions:**
-   - Open **System Settings > Notifications**
-   - Find **Script Editor** in the list
-   - Make sure notifications are set to **Banners** or **Alerts**
+```json
+{ 
+  "notificationSystem": "node-notifier" 
+}
+```
 
-### Linux: Notifications not showing
+**NOTE:** If you go with node-notifier and start missing notifications, just switch back or remove the option from the config. Users have reported issues with using node-notifier for receiving only sounds and no notification popups.
 
-1. **Install notify-send:**
+## Updating
 
-   ```bash
-   # Debian/Ubuntu
-   sudo apt install libnotify-bin
+If Opencode does not update the plugin or there is an issue with the cache version:
 
-   # Fedora
-   sudo dnf install libnotify
+```bash
+# Linux/macOS
+rm -rf ~/.cache/opencode/node_modules/@mohak34/opencode-notifier
 
-   # Arch
-   sudo pacman -S libnotify
-   ```
+# Windows
+Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\node_modules\@mohak34\opencode-notifier"
+```
 
-2. **Test if it works:**
+Then restart OpenCode.
 
-   ```bash
-   notify-send "Test" "Hello"
-   ```
+## Troubleshooting
 
-### Linux: Sounds not playing
+**macOS: Not seeing notifications?**
+Go to System Settings > Notifications > Script Editor, make sure it's set to Banners or Alerts.
 
-Install one of these audio players: `paplay`, `aplay`, `mpv`, or `ffplay`.
+**macOS: node-notifier not showing notifications?**
+Switch back to osascript. Some users report node-notifier works for sounds but not visual notifications on certain macOS versions.
 
+**Linux: No notifications?**
+Install libnotify-bin:
 ```bash
-# Debian/Ubuntu (PulseAudio)
-sudo apt install pulseaudio-utils
-
-# Or install mpv
-sudo apt install mpv
+sudo apt install libnotify-bin  # Debian/Ubuntu
+sudo dnf install libnotify       # Fedora
+sudo pacman -S libnotify         # Arch
 ```
 
-### Windows: Notifications not showing
+Test with: `notify-send "Test" "Hello"`
+
+**Linux: No sounds?**
+Install one of: `paplay`, `aplay`, `mpv`, or `ffplay`
 
-1. Open **Settings > System > Notifications**
-2. Make sure notifications are enabled
-3. Check that your terminal app has notification permissions
+**Windows: Custom sounds not working?**
+- Must be .wav format (not .mp3)
+- Use full Windows paths: `C:/Users/YourName/sounds/alert.wav` (not `~/`)
+- Make sure the file actually plays in Windows Media Player
+- If using WSL, the path should be accessible from Windows
+
+**Windows WSL notifications not working?**
+WSL doesn't have a native notification daemon. Use PowerShell commands instead:
+
+```json
+{
+  "notification": false,
+  "sound": true,
+  "command": {
+    "enabled": true,
+    "path": "powershell.exe",
+    "args": [
+      "-Command",
+      "$wshell = New-Object -ComObject Wscript.Shell; $wshell.Popup('{message}', 5, 'OpenCode - {event}', 0+64)"
+    ]
+  }
+}
+```
 
-### General: Plugin not loading
+**Windows: OpenCode crashes when notifications appear?**
+This is a known Bun issue on Windows. Disable native notifications and use PowerShell popups:
 
-1. **Check your opencode.json syntax:**
+```json
+{
+  "notification": false,
+  "sound": true,
+  "command": {
+    "enabled": true,
+    "path": "powershell.exe",
+    "args": [
+      "-Command",
+      "$wshell = New-Object -ComObject Wscript.Shell; $wshell.Popup('{message}', 5, 'OpenCode - {event}', 0+64)"
+    ]
+  }
+}
+```
 
-   ```json
-   {
-     "plugin": ["@mohak34/opencode-notifier@latest"]
-   }
-   ```
+**Plugin not loading?**
+- Check your opencode.json syntax
+- Clear the cache (see Updating section)
+- Restart OpenCode
 
-2. **Clear the cache and restart:**
+## Changelog
 
-   ```bash
-   rm -rf ~/.cache/opencode/node_modules/@mohak34/opencode-notifier
-   ```
+See [CHANGELOG.md](CHANGELOG.md)
 
 ## License
 

package/dist/index.js

@@ -3770,6 +3770,13 @@ var DEFAULT_CONFIG = {
     subagent_complete: null,
     error: null,
     question: null
+  },
+  volumes: {
+    permission: 1,
+    complete: 1,
+    subagent_complete: 1,
+    error: 1,
+    question: 1
   }
 };
 function getConfigPath() {
@@ -3790,6 +3797,18 @@ function parseEventConfig(userEvent, defaultConfig) {
     notification: userEvent.notification ?? defaultConfig.notification
   };
 }
+function parseVolume(value, defaultVolume) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return defaultVolume;
+  }
+  if (value < 0) {
+    return 0;
+  }
+  if (value > 1) {
+    return 1;
+  }
+  return value;
+}
 function loadConfig() {
   const configPath = getConfigPath();
   if (!existsSync(configPath)) {
@@ -3840,6 +3859,13 @@ function loadConfig() {
         subagent_complete: userConfig.sounds?.subagent_complete ?? DEFAULT_CONFIG.sounds.subagent_complete,
         error: userConfig.sounds?.error ?? DEFAULT_CONFIG.sounds.error,
         question: userConfig.sounds?.question ?? DEFAULT_CONFIG.sounds.question
+      },
+      volumes: {
+        permission: parseVolume(userConfig.volumes?.permission, DEFAULT_CONFIG.volumes.permission),
+        complete: parseVolume(userConfig.volumes?.complete, DEFAULT_CONFIG.volumes.complete),
+        subagent_complete: parseVolume(userConfig.volumes?.subagent_complete, DEFAULT_CONFIG.volumes.subagent_complete),
+        error: parseVolume(userConfig.volumes?.error, DEFAULT_CONFIG.volumes.error),
+        question: parseVolume(userConfig.volumes?.question, DEFAULT_CONFIG.volumes.question)
       }
     };
   } catch {
@@ -3858,6 +3884,9 @@ function getMessage(config, event) {
 function getSoundPath(config, event) {
   return config.sounds[event];
 }
+function getSoundVolume(config, event) {
+  return config.volumes[event];
+}
 function getIconPath(config) {
   if (!config.showIcon) {
     return;
@@ -3939,6 +3968,8 @@ import { existsSync as existsSync2 } from "fs";
 import { spawn } from "child_process";
 var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
 var DEBOUNCE_MS2 = 1000;
+var FULL_VOLUME_PERCENT = 100;
+var FULL_VOLUME_PULSE = 65536;
 var lastSoundTime = {};
 function getBundledSoundPath(event) {
   const soundFilename = `${event}.wav`;
@@ -3981,12 +4012,32 @@ async function runCommand(command, args) {
     });
   });
 }
-async function playOnLinux(soundPath) {
+function normalizeVolume(volume) {
+  if (!Number.isFinite(volume)) {
+    return 1;
+  }
+  if (volume < 0) {
+    return 0;
+  }
+  if (volume > 1) {
+    return 1;
+  }
+  return volume;
+}
+function toPercentVolume(volume) {
+  return Math.round(volume * FULL_VOLUME_PERCENT);
+}
+function toPulseVolume(volume) {
+  return Math.round(volume * FULL_VOLUME_PULSE);
+}
+async function playOnLinux(soundPath, volume) {
+  const percentVolume = toPercentVolume(volume);
+  const pulseVolume = toPulseVolume(volume);
   const players = [
-    { command: "paplay", args: [soundPath] },
+    { command: "paplay", args: [`--volume=${pulseVolume}`, soundPath] },
     { command: "aplay", args: [soundPath] },
-    { command: "mpv", args: ["--no-video", "--no-terminal", soundPath] },
-    { command: "ffplay", args: ["-nodisp", "-autoexit", "-loglevel", "quiet", soundPath] }
+    { command: "mpv", args: ["--no-video", "--no-terminal", `--volume=${percentVolume}`, soundPath] },
+    { command: "ffplay", args: ["-nodisp", "-autoexit", "-loglevel", "quiet", "-volume", `${percentVolume}`, soundPath] }
   ];
   for (const player of players) {
     try {
@@ -3997,20 +4048,21 @@ async function playOnLinux(soundPath) {
     }
   }
 }
-async function playOnMac(soundPath) {
-  await runCommand("afplay", [soundPath]);
+async function playOnMac(soundPath, volume) {
+  await runCommand("afplay", ["-v", `${volume}`, soundPath]);
 }
 async function playOnWindows(soundPath) {
   const script = `& { (New-Object Media.SoundPlayer $args[0]).PlaySync() }`;
   await runCommand("powershell", ["-c", script, soundPath]);
 }
-async function playSound(event, customPath) {
+async function playSound(event, customPath, volume) {
   const now = Date.now();
   if (lastSoundTime[event] && now - lastSoundTime[event] < DEBOUNCE_MS2) {
     return;
   }
   lastSoundTime[event] = now;
   const soundPath = getSoundFilePath(event, customPath);
+  const normalizedVolume = normalizeVolume(volume);
   if (!soundPath) {
     return;
   }
@@ -4018,10 +4070,10 @@ async function playSound(event, customPath) {
   try {
     switch (os2) {
       case "darwin":
-        await playOnMac(soundPath);
+        await playOnMac(soundPath, normalizedVolume);
         break;
       case "linux":
-        await playOnLinux(soundPath);
+        await playOnLinux(soundPath, normalizedVolume);
         break;
       case "win32":
         await playOnWindows(soundPath);
@@ -4068,7 +4120,8 @@ async function handleEvent(config, eventType, projectName, elapsedSeconds) {
   }
   if (isEventSoundEnabled(config, eventType)) {
     const customSoundPath = getSoundPath(config, eventType);
-    promises.push(playSound(eventType, customSoundPath));
+    const soundVolume = getSoundVolume(config, eventType);
+    promises.push(playSound(eventType, customSoundPath, soundVolume));
   }
   const minDuration = config.command?.minDuration;
   const shouldSkipCommand = typeof minDuration === "number" && Number.isFinite(minDuration) && minDuration > 0 && typeof elapsedSeconds === "number" && Number.isFinite(elapsedSeconds) && elapsedSeconds < minDuration;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohak34/opencode-notifier",
-  "version": "0.1.19",
+  "version": "0.1.20-beta.0",
   "description": "OpenCode plugin that sends system notifications and plays sounds when permission is needed, generation completes, or errors occur",
   "author": "mohak34",
   "license": "MIT",