{
  "markdown": "![Claude Code Plugin](https://img.shields.io/badge/Claude_Code-Plugin-blueviolet)\n![Platform](https://img.shields.io/badge/platform-macOS%20|%20Linux%20|%20Windows%20|%20WSL-lightgrey)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n# notif-sound\n\n> **Never miss when Claude needs your attention.**\n\n## The Problem\n\nI open Claude Code, prompt something, switch tabs, lose focus — and don't even realize it's already finished or waiting for my next action. That's kinda frustrating. There's no official notification solution.  i checked — Claude Code runs completely silent. no sound.\n\nSo that's why I built this **notif-sound** plugin. It plays a sound the moment Claude needs my attention. I’ve been using it personally, and i’m sharing it here for anyone facing the same issue. sure, you can set this up yourself with scripts and Claude hooks — but this plugin makes it more simple.\n\n## Demo\n\nhttps://www.loom.com/share/df2f1bc12d5d405ca79439c756cc3919\n\n<!-- Video demo will be added here -->\n\n## Getting Started\n\nYou don't need to be a developer to set this up. Just follow these steps inside Claude Code:\n\n### Prerequisites\n\nYou likely already have everything you need. The plugin uses tools that come pre-installed on most systems and auto-detects available Python versions.\n\n| Platform | What you need | Already installed? |\n|----------|--------------|-------------------|\n| **macOS** | `afplay`, Python 3 | Yes — `afplay` is built-in. Python auto-detects `python3` or `python` |\n| **Linux** | Python 3, `paplay` or `aplay` | Usually yes — auto-detects `python3`, `python`, or `py` |\n| **Windows** | Python 3, `powershell` | `powershell` is built-in. Install Python 3 from [python.org](https://www.python.org/downloads/) or via `winget install Python.Python.3`. Auto-detects `python`, `python3`, or `py` |\n| **WSL** | Python 3 | Yes — pre-installed. Auto-detects `python3`, `python`, or `py` |\n\n### Installation\n\n**Step 1** — Add the plugin marketplace:\n\n```\n/plugin marketplace add juuni26/claude-plugins-marketplace\n```\n\n**Step 2** — Install the plugin:\n\n```\n/plugin install notif-sound\n```\n\n**Step 3** — Reload plugins to activate:\n\n```\n/reload-plugins\n```\n\n**Step 4** — Verify everything works:\n\n```\n/notif-sound:verify\n```\n\nClaude will run a few checks and ask for permission to execute the verification scripts. **Allow the permissions** — this is just the plugin checking that sounds can play on your system.\n\nIf all checks pass, you're done. Notification sounds will now play automatically whenever Claude finishes, asks a question, or needs your approval.\n\n> **Tip:** Run `/notif-sound:test` to hear what it sounds like.\n\n## GUI Dashboard\n\nThe easiest way to manage your sounds and settings is through the built-in web dashboard.\n\n**Launch it:**\n\n```\n/notif-sound:gui\n```\n\n<img width=\"1546\" height=\"1850\" alt=\"image\" src=\"https://github.com/user-attachments/assets/830145bb-0fcd-4352-800a-7304f88422cf\" />\n\n\nThis opens a web dashboard at `http://localhost:6998` where you can:\n\n- **Adjust volume** — drag the slider from 1 to 10 (macOS/Linux only; hidden on Windows)\n- **Preview sounds** — click play on any sound in your library\n- **Add new sounds** — drag and drop `.wav` files (Windows) or `.mp3`/`.wav` files (macOS/Linux) right into the browser\n- **Remove sounds** — hover over a sound and click the delete button\n- **Check status** — see at a glance if everything is working\n\nTo stop the dashboard server:\n\n```\n/notif-sound:gui stop\n```\n\n<!-- GUI screenshot/video will be added here -->\n\n## Features\n\n- **4 hook events** — Stop, PreToolUse (AskUserQuestion), PermissionRequest, Notification\n- **Volume control** — intuitive 1-10 scale via `/notif-sound:volume` or GUI slider (macOS/Linux only; Windows uses system volume)\n- **Custom sounds** — add your own sound files, a random one plays each time\n- **Web GUI dashboard** — visual sound management at `localhost:6998`\n- **Smart dedup** — PID-based tracking skips if a sound is already playing\n- **Cross-OS** — macOS (`afplay`), Linux (`paplay`/`aplay`), Windows (`powershell`), WSL (`powershell.exe`)\n- **Minimal dependencies** — uses built-in OS audio tools + Python 3\n- **Non-blocking** — all playback runs in background, never slows down Claude\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/notif-sound:test` | Play a test sound |\n| `/notif-sound:volume <1-10>` | Set volume level (macOS/Linux only) |\n| `/notif-sound:list` | List all sounds |\n| `/notif-sound:add <path>` | Add a sound file |\n| `/notif-sound:remove <name>` | Remove a sound file |\n| `/notif-sound:gui` | Open web dashboard |\n| `/notif-sound:status` | Check plugin health |\n| `/notif-sound:verify` | Verify setup and fix issues |\n| `/notif-sound:uninstall` | Cleanly remove the plugin |\n\n---\n\n## Advanced\n\n### Hook Events\n\n| Event | Trigger | Why it matters |\n|-------|---------|----------------|\n| `Stop` | Claude finished responding | Know when to come back |\n| `Notification` | Background agent done | Don't miss async results |\n| `PreToolUse` (AskUserQuestion) | Claude asks you a question | Blockers need fast response |\n| `PermissionRequest` | Claude needs tool approval | Blockers need fast response |\n\n### OS Support\n\n| OS | Audio Player | Volume Control | Formats |\n|----|-------------|---------------|---------|\n| macOS | `afplay` | Yes (0.0-1.0) | .mp3, .wav, .aac, .m4a |\n| Linux | `paplay` (primary), `aplay` (fallback) | Yes (`paplay`), No (`aplay`) | .mp3 (`paplay`), .wav (both) |\n| Windows | `powershell` (`Media.SoundPlayer`) | No (system volume) | .wav only |\n| WSL | `paplay` (if available), `powershell.exe` (fallback) | Yes (`paplay`), No (PowerShell) | .mp3 (`paplay`), .wav (PowerShell) |\n\n> **Windows note:** Only `.wav` files are supported on native Windows because PowerShell's `Media.SoundPlayer` does not support `.mp3`. The plugin ships with `default.wav` which works out of the box.\n\n### Volume\n\nVolume is a **limiter**, not an amplifier. Setting it to 10 means 100% of your system volume — to go louder, turn up your OS volume.\n\n| Volume | macOS (`afplay -v`) | Linux (`paplay --volume`) |\n|--------|---------------------|---------------------------|\n| 1 | 0.1 (10%) | 6,554 (~10%) |\n| 4 (default) | 0.4 (40%) | 26,214 (~40%) |\n| 7 | 0.7 (70%) | 45,875 (~70%) |\n| 10 | 1.0 (100%) | 65,536 (100%) |\n\n> WSL's PowerShell `SoundPlayer` does not support volume control — sounds play at system volume.\n\n### Local Install (Alternative)\n\nIf you prefer not to use the marketplace:\n\n```bash\n# Clone the plugin\ngit clone https://github.com/juuni26/claude-notif-sound.git ~/.claude/plugins/local/notif-sound\n\n# Make scripts executable\nchmod +x ~/.claude/plugins/local/notif-sound/scripts/*.sh\n\n# Launch Claude with the plugin\nclaude --plugin-dir ~/.claude/plugins/local/notif-sound\n```\n\n### Custom Sounds\n\nThe plugin ships with `default.mp3` and `default.wav` — royalty-free sounds from [Pixabay](https://pixabay.com/sound-effects/technology-new-notification-036-485897/). Add your own files for variety — a random sound is picked each time a hook fires.\n\n```bash\n# Use the slash command\n/notif-sound:add ~/my-sound.wav\n\n# Or drag and drop via the web GUI\n/notif-sound:gui\n```\n\n```\nsounds/\n  default.mp3          # included sample\n  default.wav          # WAV version (Windows compatible)\n  my-notification.wav  # your custom sounds\n```\n\n### How Deduplication Works\n\nMultiple hooks can fire in rapid succession (e.g., `AskUserQuestion` + `Stop`). The plugin uses PID-based tracking to prevent overlapping sounds — before playing, it checks if a previous audio process is still alive via `kill -0`. If yes, it skips the new sound.\n\n### Plugin Structure\n\n```\nnotif-sound/\n├── .claude-plugin/\n│   └── plugin.json          # Plugin metadata\n├── hooks/\n│   └── hooks.json           # Hook definitions\n├── scripts/\n│   ├── play-sound.sh        # Main playback engine\n│   ├── gui-server.sh        # Web GUI launcher\n│   └── gui-server.py        # Web GUI API server\n├── commands/\n│   ├── add.md               # /notif-sound:add\n│   ├── gui.md               # /notif-sound:gui\n│   ├── list.md              # /notif-sound:list\n│   ├── remove.md            # /notif-sound:remove\n│   ├── status.md            # /notif-sound:status\n│   ├── test.md              # /notif-sound:test\n│   ├── uninstall.md         # /notif-sound:uninstall\n│   ├── verify.md            # /notif-sound:verify\n│   └── volume.md            # /notif-sound:volume\n├── gui/\n│   └── index.html           # Single-file web dashboard\n├── sounds/                  # Drop sound files here\n│   ├── default.mp3          # Included sample\n│   └── default.wav          # WAV version\n├── .gitignore\n└── LICENSE\n```\n\n### How It Works\n\nThis plugin uses [Claude Code hooks](https://code.claude.com/docs/en/hooks) — user-defined shell commands that execute automatically at specific lifecycle points. When a hook event fires, Claude Code runs `play-sound.sh` which:\n\n1. Checks if a previous sound is still playing (PID-based dedup) — skips if so\n2. Reads volume from `config.json`\n3. Picks a random sound from `sounds/`\n4. Plays it in the background via the OS audio player\n5. Sends a terminal bell (`\\a`) for Dock bounce / taskbar flash\n\n#### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `CLAUDE_PLUGIN_ROOT` | Plugin installation directory (set by Claude Code) |\n| `CLAUDE_PLUGIN_DATA` | Persistent data directory (survives plugin updates) |\n\n## Tested On\n\n- Windows 11\n- macOS Tahoe\n\n## References\n\n- [Claude Code Hooks](https://code.claude.com/docs/en/hooks) — full hooks reference\n- [Claude Code Documentation](https://code.claude.com/docs) — full docs index\n",
  "bytes": 9641,
  "sha": "e08fbb04fcbae7d216256d6a5f3ef09b18217aa23c3b4655fb3af3211b1c96a0",
  "repo_slug": "juuni26/claude-notif-sound",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_juuni26_claude_notif_sound_notif_sound_118b92e6/readme"
}