notif-sound
A Claude Code plugin that plays notification sounds when Claude finishes responding, asks a question, or needs permission — never miss when
Open source Open in the app JSON README (API)
About
A Claude Code plugin that plays notification sounds when Claude finishes responding, asks a question, or needs permission — never miss when Claude needs your attention.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- juuni26
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 2
- Last push
- 2026-04-02T17:29:18Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
juuni26/claude-notif-sound/notif-sound
README
   # notif-sound > **Never miss when Claude needs your attention.** ## The Problem I 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. So 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. ## Demo https://www.loom.com/share/df2f1bc12d5d405ca79439c756cc3919 <!-- Video demo will be added here --> ## Getting Started You don't need to be a developer to set this up. Just follow these steps inside Claude Code: ### Prerequisites You likely already have everything you need. The plugin uses tools that come pre-installed on most systems and auto-detects available Python versions. | Platform | What you need | Already installed? | |----------|--------------|-------------------| | **macOS** | `afplay`, Python 3 | Yes — `afplay` is built-in. Python auto-detects `python3` or `python` | | **Linux** | Python 3, `paplay` or `aplay` | Usually yes — auto-detects `python3`, `python`, or `py` | | **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` | | **WSL** | Python 3 | Yes — pre-installed. Auto-detects `python3`, `python`, or `py` | ### Installation **Step 1** — Add the plugin marketplace: ``` /plugin marketplace add juuni26/claude-plugins-marketplace ``` **Step 2** — Install the plugin: ``` /plugin install notif-sound ``` **Step 3** — Reload plugins to activate: ``` /reload-plugins ``` **Step 4** — Verify everything works: ``` /notif-sound:verify ``` Claude 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. If all checks pass, you're done. Notification sounds will now play automatically whenever Claude finishes, asks a question, or needs your approval. > **Tip:** Run `/notif-sound:test` to hear what it sounds like. ## GUI Dashboard The easiest way to manage your sounds and settings is through the built-in web dashboard. **Launch it:** ``` /notif-sound:gui ``` <img width="1546" height="1850" alt="image" src="https://github.com/user-attachments/assets/830145bb-0fcd-4352-800a-7304f88422cf" /> This opens a web dashboard at `http://localhost:6998` where you can: - **Adjust volume** — drag the slider from 1 to 10 (macOS/Linux only; hidden on Windows) - **Preview sounds** — click play on any sound in your library - **Add new sounds** — drag and drop `.wav` files (Windows) or `.mp3`/`.wav` files (macOS/Linux) right into the browser - **Remove sounds** — hover over a sound and click the delete button - **Check status** — see at a glance if everything is working To stop the dashboard server: ``` /notif-sound:gui stop ``` <!-- GUI screenshot/video will be added here --> ## Features - **4 hook events** — Stop, PreToolUse (AskUserQuestion), PermissionRequest, Notification - **Volume control** — intuitive 1-10 scale via `/notif-sound:volume` or GUI slider (macOS/Linux only; Windows uses system volume) - **Custom sounds** — add your own sound files, a random one plays each time - **Web GUI dashboard** — visual sound management at `localhost:6998` - **Smart dedup** — PID-based tracking skips if a sound is already playing - **Cross-OS** — macOS (`afplay`), Linux (`paplay`/`aplay`), Windows (`powershell`), WSL (`powershell.exe`) - **Minimal dependencies** — uses built-in OS audio tools + Python 3 - **Non-blocking** — all playback runs in background, never slows down Claude ## Commands | Command | Description | |---------|-------------| | `/notif-sound:test` | Play a test sound | | `/notif-sound:volume <1-10>` | Set volume level (macOS/Linux only) | | `/notif-sound:list` | List all sounds | | `/notif-sound:add <path>` | Add a sound file | | `/notif-sound:remove <name>` | Remove a sound file | | `/notif-sound:gui` | Open web dashboard | | `/notif-sound:status` | Check plugin health | | `/notif-sound:verify` | Verify setup and fix issues | | `/notif-sound:uninstall` | Cleanly remove the plugin | --- ## Advanced ### Hook Events | Event | Trigger | Why it matters | |-------|---------|----------------| | `Stop` | Claude finished responding | Know when to come back | | `Notification` | Background agent done | Don't miss async results | | `PreToolUse` (AskUserQuestion) | Claude asks you a question | Blockers need fast response | | `PermissionRequest` | Claude needs tool approval | Blockers need fast response | ### OS Support | OS | Audio Player | Volume Control | Formats | |----|-------------|---------------|---------| | macOS | `afplay` | Yes (0.0-1.0) | .mp3, .wav, .aac, .m4a | | Linux | `paplay` (primary), `aplay` (fallback) | Yes (`paplay`), No (`aplay`) | .mp3 (`paplay`), .wav (both) | | Windows | `powershell` (`Media.SoundPlayer`) | No (system volume) | .wav only | | WSL | `paplay` (if available), `powershell.exe` (fallback) | Yes (`paplay`), No (PowerShell) | .mp3 (`paplay`), .wav (PowerShell) | > **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. ### Volume Volume is a **limiter**, not an amplifier. Setting it to 10 means 100% of your system volume — to go louder, turn up your OS volume. | Volume | macOS (`afplay -v`) | Linux (`paplay --volume`) | |--------|---------------------|---------------------------| | 1 | 0.1 (10%) | 6,554 (~10%) | | 4 (default) | 0.4 (40%) | 26,214 (~40%) | | 7 | 0.7 (70%) | 45,875 (~70%) | | 10 | 1.0 (100%) | 65,536 (100%) | > WSL's PowerShell `SoundPlayer` does not support volume control — sounds play at system volume. ### Local Install (Alternative) If you prefer not to use the marketplace: ```bash # Clone the plugin git clone https://github.com/juuni26/claude-notif-sound.git ~/.claude/plugins/local/notif-sound # Make scripts executable chmod +x ~/.claude/plugins/local/notif-sound/scripts/*.sh # Launch Claude with the plugin claude --plugin-dir ~/.claude/plugins/local/notif-sound ``` ### Custom Sounds The 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. ```bash # Use the slash command /notif-sound:add ~/my-sound.wav # Or drag and drop via the web GUI /notif-sound:gui ``` ``` sounds/ default.mp3 # included sample default.wav # WAV version (Windows compatible) my-notification.wav # your custom sounds ``` ### How Deduplication Works Multiple 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. ### Plugin Structure ``` notif-sound/ ├── .claude-plugin/ │ └── plugin.json # Plugin metadata ├── hooks/ │ └── hooks.json # Hook definitions ├── scripts/ │ ├── play-sound.sh # Main playback engine │ ├── gui-server.sh # Web GUI launcher │ └── gui-server.py # Web GUI API server ├── commands/ │ ├── add.md # /notif-sound:add │ ├── gui.md # /notif-sound:gui │ ├── list.md # /notif-sound:list │ ├── remove.md # /notif-sound:remove │ ├── status.md # /notif-sound:status │ ├── test.md # /notif-sound:test │ ├── uninstall.md # /notif-sound:uninstall │ ├── verify.md # /notif-sound:verify │ └── volume.md # /notif-sound:volume ├── gui/ │ └── index.html # Single-file web dashboard ├── sounds/ # Drop sound files here │ ├── default.mp3 # Included sample │ └── default.wav # WAV version ├── .gitignore └── LICENSE ``` ### How It Works This 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: 1. Checks if a previous sound is still playing (PID-based dedup) — skips if so 2. Reads volume from `config.json` 3. Picks a random sound from `sounds/` 4. Plays it in the background via the OS audio player 5. Sends a terminal bell (`\a`) for Dock bounce / taskbar flash #### Environment Variables | Variable | Description | |----------|-------------| | `CLAUDE_PLUGIN_ROOT` | Plugin installation directory (set by Claude Code) | | `CLAUDE_PLUGIN_DATA` | Persistent data directory (survives plugin updates) | ## Tested On - Windows 11 - macOS Tahoe ## References - [Claude Code Hooks](https://code.claude.com/docs/en/hooks) — full hooks reference - [Claude Code Documentation](https://code.claude.com/docs) — full docs index