opencode-plugin-boops 1.0.0 → 2.0.2

package/README.md

@@ -4,18 +4,28 @@ Sound notifications for OpenCode - plays pleasant "boop" sounds when tasks compl
 
 ## Features
 
-- 🎵 Pleasant glass chime when AI completes a response
-- 📡 Sonar ping when AI needs your permission or input
-- 🔄 Automatic fallback to alternative sounds if preferred sounds aren't available
+- 🎵 Soft, friendly notification sounds when AI completes tasks
+- 📡 Gentle alert when AI needs your permission or input
+- 🌐 Works out of the box with online sounds (auto-downloaded and cached)
+- 🔄 Fully configurable - use URLs or local files
 - 🐧 Works on Linux (with `paplay` or `aplay`)
-- 🍎 Works on macOS (requires custom sound configuration)
+- 🍎 Works on macOS (with `afplay`)
 
 ## Installation
 
-### Using OpenCode config
+Add to your OpenCode config file:
 
-Add to your `opencode.json` or `~/.config/opencode/opencode.json`:
+**Global installation** (recommended):
+```bash
+# Edit ~/.config/opencode/opencode.json
+```
+
+**Per-project installation**:
+```bash
+# Edit opencode.json in your project root
+```
 
+Add the plugin to the config:
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
@@ -23,51 +33,238 @@ Add to your `opencode.json` or `~/.config/opencode/opencode.json`:
 }
 ```
 
-### Manual installation
+Then restart OpenCode. The plugin will be automatically downloaded and installed from npm.
 
-Place the plugin file in your OpenCode plugins directory:
+### Quick setup
+
+If you don't have an OpenCode config yet:
 
 ```bash
-# Global
-mkdir -p ~/.config/opencode/plugins
-cp index.ts ~/.config/opencode/plugins/boops.ts
+# Create global config
+mkdir -p ~/.config/opencode
+echo '{"$schema":"https://opencode.ai/config.json","plugin":["opencode-plugin-boops"]}' > ~/.config/opencode/opencode.json
+```
+
+Or for a specific project:
 
-# Per-project
-mkdir -p .opencode/plugins
-cp index.ts .opencode/plugins/boops.ts
+```bash
+# In your project directory
+echo '{"$schema":"https://opencode.ai/config.json","plugin":["opencode-plugin-boops"]}' > opencode.json
 ```
 
 ## How it works
 
-The plugin listens to OpenCode events:
+The plugin listens to OpenCode events and plays sounds based on your configuration. By default, it uses online sounds that are automatically downloaded and cached:
+
+- **`session.idle`** - AI finishes responding → soft "pristine" notification
+- **`permission.asked`** - AI needs permission → gentle "relax" chime
+- **`session.error`** - An error occurs → friendly "magic" alert
+
+Sounds are downloaded once on first use and cached in `~/.cache/opencode/boops/` for instant playback.
+
+## Configuration
+
+The plugin automatically creates a configuration file at `~/.config/opencode/plugins/boops/boops.toml` on first install.
+
+### Customize your config
+
+The config is automatically created from `boops.default.toml` when you install the plugin. Edit it to customize your sounds:
+
+```bash
+# Edit your config
+$EDITOR ~/.config/opencode/plugins/boops/boops.toml
+```
+
+Example configuration:
+
+```toml
+# ~/.config/opencode/plugins/boops/boops.toml
 
-- **`session.idle`** - Fires when the AI finishes responding → plays completion sound (glass.ogg)
-- **`permission.asked`** - Fires when the AI needs permission → plays attention sound (sonar.ogg)
+[sounds]
+# Use sound names from sounds.json (recommended)
+"session.idle" = "pristine"
+"permission.asked" = "relax"
+"session.error" = "magic"
 
-## Customization
+# Or use full URLs:
+# "session.idle" = "https://example.com/sound.ogg"
 
-### Custom sounds
+# Or use local file paths:
+# "session.idle" = "/usr/share/sounds/gnome/default/alerts/drip.ogg"
+```
+
+### Sound sources
 
-To use your own sounds, modify the sound file paths in `index.ts`:
+The plugin supports multiple ways to specify sounds:
 
-```typescript
-const inputSound = '/path/to/your/input-sound.ogg'
-const completeSound = '/path/to/your/complete-sound.ogg'
+**1. Sound names from sounds.json (easiest):**
+```toml
+"session.idle" = "pristine"
+"permission.asked" = "relax"
+"session.error" = "magic"
 ```
 
-### macOS
+Use the TUI browser (`~/.config/opencode/plugins/boops/browse`) to explore all 448 sounds with semantic tags!
 
-On macOS, you can use system sounds:
+**2. Full URLs:**
+```toml
+"session.idle" = "https://example.com/sound.ogg"
+```
 
-```typescript
-const inputSound = '/System/Library/Sounds/Ping.aiff'
-const completeSound = '/System/Library/Sounds/Glass.aiff'
+**3. Local file paths:**
+```toml
+"session.idle" = "/usr/share/sounds/gnome/default/alerts/drip.ogg"
 ```
 
-And update the `playSound` function to use `afplay`:
+**Caching:** Remote sounds (IDs and URLs) are cached in `~/.cache/opencode/boops/` by event name (e.g. `session-idle`, `permission-asked`). Once downloaded, they're reused instantly. If you change a sound, the cache is automatically updated on next play.
+
+### Available events
+
+You can configure sounds for any of the 28 OpenCode events:
+
+**Session events (8):**
+- `session.idle` - AI completes response
+- `session.error` - Error occurs
+- `session.created` - New session starts
+- `session.deleted` - Session deleted
+- `session.compacted` - Session compacted
+- `session.diff` - Session diff generated
+- `session.status` - Session status changed
+- `session.updated` - Session updated
+
+**Permission events (2):**
+- `permission.asked` - AI needs permission
+- `permission.replied` - Permission response given
+
+**File events (2):**
+- `file.edited` - File is edited
+- `file.watcher.updated` - File watcher detects change
+
+**Tool events (2):**
+- `tool.execute.before` - Before tool execution
+- `tool.execute.after` - After tool execution
+
+**Message events (4):**
+- `message.part.removed` - Message part removed
+- `message.part.updated` - Message part updated
+- `message.removed` - Message removed
+- `message.updated` - Message updated
 
-```typescript
-await Bun.$`afplay ${primaryFile}`.quiet()
+**LSP events (2):**
+- `lsp.client.diagnostics` - LSP diagnostics received
+- `lsp.updated` - LSP server updated
+
+**TUI events (3):**
+- `tui.prompt.append` - Text appended to prompt
+- `tui.command.execute` - TUI command executed
+- `tui.toast.show` - Toast notification shown
+
+**Other events (5):**
+- `command.executed` - Command executed
+- `todo.updated` - Todo list updated
+- `installation.updated` - Installation/package updated
+- `server.connected` - Connected to server
+
+See the [default config](boops.default.toml) for the complete list with descriptions.
+
+### Event filters
+
+For advanced use cases, you can add filters to play sounds only when certain conditions match. This is useful for events that fire frequently or in different contexts.
+
+**Example: Only play sound for main session, not subagents:**
+
+```toml
+[sounds.session.idle]
+sound = "pristine"
+not_if = { agent = "explore" }  # Skip subagent completions
+```
+
+**How to find available properties:**
+
+1. Check OpenCode logs when the event fires:
+```bash
+tail -f ~/.local/share/opencode/log/*.log | grep "session.idle event"
+```
+
+2. The logs will show all event properties you can filter on
+
+**Filter syntax:**
+
+```toml
+[sounds.event-name]
+sound = "/path/to/sound"
+only_if = { property = "value" }  # Only play if property equals value
+not_if = { property = "value" }   # Don't play if property equals value
+```
+
+### Testing sounds
+
+You can test sounds without restarting OpenCode using the custom tool:
+
+```bash
+# Test a configured event (reloads config automatically)
+test-sound session.idle
+
+# Test a sound ID directly
+# Test by sound name
+test-sound pristine
+test-sound "access granted computer voice"
+
+# Test a URL directly  
+test-sound https://example.com/sound.ogg
+
+# Test a local file directly
+test-sound /usr/share/sounds/alert.ogg
+```
+
+This is helpful when:
+- Configuring new sounds
+- Trying different sound files before committing to config
+- Testing event filters
+- Verifying URLs/IDs work
+
+The test command automatically reloads your config file, so you can edit `boops.toml` and test immediately!
+
+### Browse sounds interactively
+
+The plugin includes a beautiful TUI for browsing and assigning sounds:
+
+```bash
+# If plugin is installed
+~/.config/opencode/plugins/boops/browse
+
+# Or try it with npx (browse-only, saving disabled)
+npx opencode-plugin-boops browse
+```
+
+Features:
+- 🎨 Browse 448 sounds with tags and descriptions
+- 🏷️ Filter by tags (music, bell, quiet, etc.)
+- 🔍 Search by name
+- 🎵 Preview sounds before assigning
+- ⚡ Assign sounds to OpenCode events (if plugin installed)
+- 🖱️ Full mouse support with hover effects
+- ⌨️ Keyboard navigation
+
+**Note**: When running via `npx`, you can browse and preview sounds, but saving assignments requires the plugin to be installed.
+
+### Custom sound player
+
+By default, the plugin auto-detects `paplay` (PulseAudio), `aplay` (ALSA), or `afplay` (macOS). You can override this:
+
+```toml
+player = "afplay"  # Force specific player
+```
+
+### macOS example
+
+```toml
+player = "afplay"
+
+[sounds]
+"session.idle" = "/System/Library/Sounds/Glass.aiff"
+"permission.asked" = "/System/Library/Sounds/Ping.aiff"
+"session.error" = "/System/Library/Sounds/Basso.aiff"
 ```
 
 ## Requirements
@@ -75,28 +272,40 @@ await Bun.$`afplay ${primaryFile}`.quiet()
 - OpenCode 1.0+
 - Linux: `paplay` (PulseAudio) or `aplay` (ALSA)
 - macOS: `afplay` (built-in)
-- Sound files at specified paths (or system sounds)
+- Internet connection (only for initial sound download)
 
 ## Troubleshooting
 
 ### No sound playing
 
-1. Check if sound files exist:
+1. **Use the test command first:**
 ```bash
-ls /usr/share/sounds/gnome/default/alerts/glass.ogg
-ls /usr/share/sounds/gnome/default/alerts/sonar.ogg
+test-sound event="session.idle"
 ```
 
-2. Test sound manually:
+2. **Check if sound player is installed:**
 ```bash
-paplay /usr/share/sounds/gnome/default/alerts/glass.ogg
+which paplay  # Linux (PulseAudio)
+which aplay   # Linux (ALSA)
+which afplay  # macOS
 ```
 
-3. Check OpenCode logs:
+3. **Check OpenCode logs:**
 ```bash
 tail -f ~/.local/share/opencode/log/*.log | grep boops
 ```
 
+4. **Check cached sounds:**
+```bash
+ls -la ~/.cache/opencode/boops/
+```
+
+5. **Clear cache and re-download:**
+```bash
+rm -rf ~/.cache/opencode/boops/
+# Then use test-sound to re-download
+```
+
 ### Sounds too loud/quiet
 
 Adjust your system volume or use different sound files.
@@ -109,6 +318,10 @@ Contributions welcome! Feel free to:
 - Improve cross-platform compatibility
 - Add more event triggers
 
+## Credits
+
+Sounds from [Notification Sounds](https://notificationsounds.com) - a wonderful collection of free notification sounds provided under Creative Commons Attribution license.
+
 ## License
 
 MIT

package/boops.default.toml

@@ -0,0 +1,70 @@
+# OpenCode Boops Plugin Configuration
+# Sounds can be local file paths OR URLs (automatically downloaded and cached)
+
+# player = "paplay"  # Auto-detected if not set (paplay/aplay/afplay)
+
+[sounds]
+"session.idle" = "pristine"  # AI completes response
+"permission.asked" = "relax"  # AI needs permission
+"session.error" = "magic"  # Error occurs
+
+# You can use:
+# - Sound names: "pristine" (searches sounds.json by name)
+# - Full URLs: "https://example.com/sound.ogg"
+# - Local paths: "/usr/share/sounds/..."
+
+# Advanced: Event filters (play sound only when conditions match)
+# Uncomment and adjust after checking logs to see available properties
+# [sounds.session.idle]
+# sound = "pristine"
+# not_if = { agent = "explore" }  # Don't play for subagent completions
+
+# Optional events (uncomment to enable):
+# Command events
+# "command.executed" = "/path/to/sound"  # Command executed
+
+# File events
+# "file.edited" = "/path/to/sound"  # File edited
+# "file.watcher.updated" = "/path/to/sound"  # File watcher detected change
+
+# Installation events
+# "installation.updated" = "/path/to/sound"  # Installation/package updated
+
+# LSP events
+# "lsp.client.diagnostics" = "/path/to/sound"  # LSP diagnostics received
+# "lsp.updated" = "/path/to/sound"  # LSP server updated
+
+# Message events
+# "message.part.removed" = "/path/to/sound"  # Message part removed
+# "message.part.updated" = "/path/to/sound"  # Message part updated
+# "message.removed" = "/path/to/sound"  # Message removed
+# "message.updated" = "/path/to/sound"  # Message updated
+
+# Permission events
+# "permission.replied" = "/path/to/sound"  # Permission response given
+
+# Server events
+# "server.connected" = "/path/to/sound"  # Connected to server
+
+# Session events
+# "session.created" = "/path/to/sound"  # New session created
+# "session.compacted" = "/path/to/sound"  # Session compacted
+# "session.deleted" = "/path/to/sound"  # Session deleted
+# "session.diff" = "/path/to/sound"  # Session diff generated
+# "session.status" = "/path/to/sound"  # Session status changed
+# "session.updated" = "/path/to/sound"  # Session updated
+
+# Todo events
+# "todo.updated" = "/path/to/sound"  # Todo list updated
+
+# Tool events
+# "tool.execute.before" = "/path/to/sound"  # Before tool execution
+# "tool.execute.after" = "/path/to/sound"  # After tool execution
+
+# TUI events
+# "tui.prompt.append" = "/path/to/sound"  # Text appended to prompt
+# "tui.command.execute" = "/path/to/sound"  # TUI command executed
+# "tui.toast.show" = "/path/to/sound"  # Toast notification shown
+
+[fallbacks]
+# default = "/usr/share/sounds/alsa/Front_Center.wav"  # Optional: local fallback if download fails