notify-sounds
Plays system sounds in Claude Code when a task finishes or when permission is needed, so you don't have to keep watching the terminal. Cross
Open source Repository Open in the app JSON README (API)
About
Plays system sounds in Claude Code when a task finishes or when permission is needed, so you don't have to keep watching the terminal. Cross-platform: macOS (afplay), Linux (PulseAudio/PipeWire), Windows (PowerShell SoundPlayer), with terminal-bell fallback. Sub-agent stops are skipped to avoid noise during multi-agent workflows.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- axgord
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 1
- Last push
- 2026-07-18T11:01:54Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
axgord/claude-notify-sounds/notify-sounds
README
# claude-notify-sounds
[](https://www.npmjs.com/package/claude-notify-sounds)
[](https://opensource.org/licenses/MIT)
A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin that plays system sounds to notify you when Claude Code finishes work or needs permission. Supports macOS, Linux, and Windows.
## Features
- Plays a sound when Claude stops working — no need to keep watching the terminal
- Plays a different sound when Claude needs permission — respond faster to approval prompts
- Cross-platform: macOS, Linux (PulseAudio/PipeWire), Windows (Git Bash)
- Falls back to terminal bell when no sound system is available
## Quick Start
Install from the Claude Code plugin marketplace:
```
claude plugin add claude-notify-sounds
```
Or install manually:
```bash
git clone https://github.com/AxGord/claude-notify-sounds.git
claude plugin add ./claude-notify-sounds
```
## How It Works
The plugin uses Claude Code [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) to play sounds on specific events:
| Hook | Sound | When |
|------|-------|------|
| `Stop` | Warning tone | Claude finishes working |
| `Notification` (permission_prompt) | Ping / message tone | Claude needs permission to proceed |
The stop sound is skipped when work is not actually finished:
- sub-agent completions (`SubagentStop`)
- background agent tasks (subagent/workflow) still running when the turn ends — they re-invoke Claude on completion, so the real finish comes later, even when Claude replies in between (`background_tasks` in the Stop hook input, Claude Code v2.1.145+; on older versions the sound always plays)
- a background shell command launched moments before the turn ends ("started it and now waiting for it") — detected by the task output file being younger than a grace window, 30 seconds by default (`CLAUDE_NOTIFY_SOUNDS_GRACE` env var overrides; `0` disables)
Long-lived background shell processes (dev servers, watchers) do not silence the sound — a turn that ends long after starting one counts as finished. Any detection failure means the sound plays.
### Platform Details
| OS | Method | Sounds |
|----|--------|--------|
| **macOS** | `afplay` | Built-in system sounds (`Basso.aiff`, `Ping.aiff`) |
| **Linux** | `paplay` / `pw-play` | Freedesktop sound theme (`.oga`) |
| **Windows** | PowerShell `SoundPlayer` | Windows Media sounds (`.wav`) |
| **Fallback** | Terminal bell (`\a`) | Default terminal bell |
## Configuration
To change sounds, edit the scripts in `scripts/` and replace the sound file path:
- **macOS** — available sounds in `/System/Library/Sounds/`
- **Linux** — freedesktop sounds in `/usr/share/sounds/freedesktop/stereo/`
- **Windows** — system sounds in `C:\Windows\Media\`
## Requirements
- **macOS** — no extra dependencies (`afplay` is built-in)
- **Linux** — `paplay` (PulseAudio/PipeWire) or `pw-play` (PipeWire native); `sound-theme-freedesktop` package for sounds
- **Windows** — Git Bash or similar bash environment with access to `powershell.exe`
## License
[MIT](LICENSE)