convez.ai
PluginProdutividadeIniciante
juuni26

Notif Sound para Claude Code

juuni26/claude-notif-sound

Sons de notificação automáticos para Claude Code em macOS, Linux, Windows e WSL

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin que toca sons de notificação quando Claude termina uma resposta, faz uma pergunta ou precisa de permissão. Nunca mais perca quando Claude precisa da sua atenção enquanto você está em outra aba.

Instalação

$npx convez-ai juuni26/claude-notif-sound

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 7 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Receber alerta sonoro quando Claude termina uma resposta longa
  • Não perder quando Claude está aguardando permissão ou input do usuário
  • Trabalhar em múltiplas abas sem perder o foco em prompts concluídos
  • Personalizar sons de notificação via dashboard web integrado

Veredito

Plugin bem pensado que resolve um problema real no fluxo de trabalho com Claude Code. Instalação simples, compatível com todos os SOs, e oferece dashboard web intuitivo para customização de sons — solução prática que merece estar na toolbelt de quem usa Claude Code regularmente.

README

A tradução para o português deste README ainda está na fila.

Claude Code Plugin Platform License

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

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.

PlatformWhat you needAlready installed?
macOSafplay, Python 3Yes — afplay is built-in. Python auto-detects python3 or python
LinuxPython 3, paplay or aplayUsually yes — auto-detects python3, python, or py
WindowsPython 3, powershellpowershell is built-in. Install Python 3 from python.org or via winget install Python.Python.3. Auto-detects python, python3, or py
WSLPython 3Yes — 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

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

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

CommandDescription
/notif-sound:testPlay a test sound
/notif-sound:volume <1-10>Set volume level (macOS/Linux only)
/notif-sound:listList all sounds
/notif-sound:add <path>Add a sound file
/notif-sound:remove <name>Remove a sound file
/notif-sound:guiOpen web dashboard
/notif-sound:statusCheck plugin health
/notif-sound:verifyVerify setup and fix issues
/notif-sound:uninstallCleanly remove the plugin

Advanced

Hook Events

EventTriggerWhy it matters
StopClaude finished respondingKnow when to come back
NotificationBackground agent doneDon't miss async results
PreToolUse (AskUserQuestion)Claude asks you a questionBlockers need fast response
PermissionRequestClaude needs tool approvalBlockers need fast response

OS Support

OSAudio PlayerVolume ControlFormats
macOSafplayYes (0.0-1.0).mp3, .wav, .aac, .m4a
Linuxpaplay (primary), aplay (fallback)Yes (paplay), No (aplay).mp3 (paplay), .wav (both)
Windowspowershell (Media.SoundPlayer)No (system volume).wav only
WSLpaplay (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.

VolumemacOS (afplay -v)Linux (paplay --volume)
10.1 (10%)6,554 (~10%)
4 (default)0.4 (40%)26,214 (~40%)
70.7 (70%)45,875 (~70%)
101.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:

# 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. Add your own files for variety — a random sound is picked each time a hook fires.

# 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 — 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

VariableDescription
CLAUDE_PLUGIN_ROOTPlugin installation directory (set by Claude Code)
CLAUDE_PLUGIN_DATAPersistent data directory (survives plugin updates)

Tested On

  • Windows 11
  • macOS Tahoe

References

Ver o original no GitHub

Bom para

Relacionados