Claude Notifier

Plays a sound and shows a notification when Claude Code finishes a task, needs permission, or asks a question.

Stop watching the screen — go grab a coffee and let Claude ping you when it needs you.

Works with VSCode, terminal CLI, vim, or any editor where you use Claude Code — on macOS, Windows, WSL, and Linux.

Install

Option 1: VSCode Extension

Install from the VS Marketplace:

code --install-extension SingularityInc.claude-notifier

Or search for "Claude Notifier" in the Extensions tab (Cmd+Shift+X / Ctrl+Shift+X).

The extension auto-configures everything on activation. Reload VSCode after installing.

Option 2: Homebrew (macOS / Linux)

brew tap ashmitb95/claude-notifier
brew install claude-notifier

If brew install fails (e.g. outdated Command Line Tools), use the curl method below.

To uninstall:

brew uninstall claude-notifier
claude-notifier-uninstall  # remove hooks from ~/.claude/settings.json

Option 3: CLI (curl)

macOS / Linux / WSL:

curl -fsSL https://raw.githubusercontent.com/ashmitb95/claude-notifier/main/install.sh | bash

To uninstall:

curl -fsSL https://raw.githubusercontent.com/ashmitb95/claude-notifier/main/uninstall.sh | bash

Windows: install the VSCode extension. It auto-configures the PowerShell hooks; no separate CLI installer is needed.

Settings

Open Settings → search "Claude Notifier" (Cmd+, / Ctrl+,), or add to your settings.json:

{
  // Per-event notification level: "sound+popup" | "sound" | "popup" | "off"
  "claudeNotifier.taskCompleted.level": "sound+popup",
  "claudeNotifier.needsPermission.level": "sound+popup",
  "claudeNotifier.asksQuestion.level": "sound+popup",

  // Per-event sound preset (see list below)
  "claudeNotifier.taskCompleted.sound": "Hero",
  "claudeNotifier.needsPermission.sound": "Glass",
  "claudeNotifier.asksQuestion.sound": "Funk"
}

Notification levels:

Sound presets:

• macOS: Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink
• Windows: Windows Notify, tada, chimes, chord, ding, notify, ringin, Windows Background
• Linux: same names as macOS — each is mapped to a freedesktop XDG sound under /usr/share/sounds/freedesktop/stereo/

The global mute toggle (status bar speaker icon or Claude Notifier: Toggle Sound in the command palette) overrides all per-event settings.

How it works

Three Claude Code hooks are registered:

Each hook reads ~/.claude/hooks/claude-notifier-config.json (synced from VSCode settings) to determine which sound to play and whether to show notifications.

On macOS, hooks use afplay and osascript. On Windows and WSL, hooks use PowerShell with NotifyIcon balloon tips and system sounds. On Linux, hooks use paplay (with aplay as fallback) for audio and notify-send for notifications — install libnotify (notify-send), a PulseAudio/PipeWire or ALSA stack, and the sound-theme-freedesktop package if they aren't already present.

Behavior

• Per-session dedup. Rapid back-to-back events within a single Claude session coalesce automatically — one notification per stage, not a flood. A stage advances when you send your next prompt or after ~30 minutes of idle time.
• Bundled fallback sounds. If the configured system sound file is missing on disk, a bundled WAV plays so you still hear something.
• Diagnostic log. View → Output → Claude Notifier shows activation, signal receipts, dedup decisions, and configuration warnings — useful when debugging "I didn't get a notification."

Clickable macOS notifications (optional)

By default, macOS attributes osascript notifications to the Script Editor bundle, so clicking one opens Script Editor instead of focusing VS Code. To get clickable notifications that focus the specific window the notification fired from, install terminal-notifier:

brew install terminal-notifier

Or use the bundled command — open the Command Palette and run "Claude Notifier: Install terminal-notifier (clickable macOS notifications)". It runs the brew install in an interactive VS Code terminal so you can see what's happening. Reload the window after install to enable it.

When terminal-notifier is present, the extension uses it automatically. When it's not, the extension falls back to the standard osascript notification (everything still works — clicks just open Script Editor).

Mute/unmute (CLI)

macOS / Linux / WSL:

touch ~/.claude/hooks/claude-notifier-muted   # mute
rm ~/.claude/hooks/claude-notifier-muted      # unmute

Windows PowerShell:

New-Item "$env:USERPROFILE\.claude\hooks\claude-notifier-muted"   # mute
Remove-Item "$env:USERPROFILE\.claude\hooks\claude-notifier-muted" # unmute

Platform support

Contributing

See CONTRIBUTING.md for dev setup, the test/lint/typecheck gates, code map, and PR conventions. Bug reports and feature requests are welcome — open an issue first to discuss.

Contributors

Thanks to everyone who has contributed to this project:

License

GPL-3.0