{
  "markdown": "# claude-notify-sounds\n\n[![npm version](https://img.shields.io/npm/v/claude-notify-sounds.svg)](https://www.npmjs.com/package/claude-notify-sounds)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA [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.\n\n## Features\n\n- Plays a sound when Claude stops working — no need to keep watching the terminal\n- Plays a different sound when Claude needs permission — respond faster to approval prompts\n- Cross-platform: macOS, Linux (PulseAudio/PipeWire), Windows (Git Bash)\n- Falls back to terminal bell when no sound system is available\n\n## Quick Start\n\nInstall from the Claude Code plugin marketplace:\n\n```\nclaude plugin add claude-notify-sounds\n```\n\nOr install manually:\n\n```bash\ngit clone https://github.com/AxGord/claude-notify-sounds.git\nclaude plugin add ./claude-notify-sounds\n```\n\n## How It Works\n\nThe plugin uses Claude Code [hooks](https://docs.anthropic.com/en/docs/claude-code/hooks) to play sounds on specific events:\n\n| Hook | Sound | When |\n|------|-------|------|\n| `Stop` | Warning tone | Claude finishes working |\n| `Notification` (permission_prompt) | Ping / message tone | Claude needs permission to proceed |\n\nThe stop sound is skipped when work is not actually finished:\n\n- sub-agent completions (`SubagentStop`)\n- 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)\n- 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)\n\nLong-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.\n\n### Platform Details\n\n| OS | Method | Sounds |\n|----|--------|--------|\n| **macOS** | `afplay` | Built-in system sounds (`Basso.aiff`, `Ping.aiff`) |\n| **Linux** | `paplay` / `pw-play` | Freedesktop sound theme (`.oga`) |\n| **Windows** | PowerShell `SoundPlayer` | Windows Media sounds (`.wav`) |\n| **Fallback** | Terminal bell (`\\a`) | Default terminal bell |\n\n## Configuration\n\nTo change sounds, edit the scripts in `scripts/` and replace the sound file path:\n\n- **macOS** — available sounds in `/System/Library/Sounds/`\n- **Linux** — freedesktop sounds in `/usr/share/sounds/freedesktop/stereo/`\n- **Windows** — system sounds in `C:\\Windows\\Media\\`\n\n## Requirements\n\n- **macOS** — no extra dependencies (`afplay` is built-in)\n- **Linux** — `paplay` (PulseAudio/PipeWire) or `pw-play` (PipeWire native); `sound-theme-freedesktop` package for sounds\n- **Windows** — Git Bash or similar bash environment with access to `powershell.exe`\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 3193,
  "sha": "ba0587f67239569e408b433a55277fd1724f58590794165790d32ed6eea3deea",
  "repo_slug": "axgord/claude-notify-sounds",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_axgord_claude_notify_sounds_notify_sound_ba1e183e/readme"
}