claude-code-ding

Audio notifications for Claude Code — never miss when your AI pair programmer needs you.

Stop staring at your terminal. claude-code-ding plays distinct sounds when Claude Code asks a question, finishes a task, or needs your input — so you can context-switch freely and come back the moment you're needed.

Works on Windows, macOS, and Linux. Zero dependencies. Installs in 30 seconds.

---

Why?

Claude Code runs autonomously — sometimes for minutes at a time. Without notifications, you're either:

• Watching the terminal doing nothing, waiting for it to finish
• Switching to another task and forgetting to check back, losing momentum

claude-code-ding solves this with three distinct audio alerts:

Sound	Event	What it means
🔔 Three quick ascending beeps	Question asked	Claude needs your answer to continue
🔔 Two medium beeps	Stopped / needs input	Claude finished responding, your turn
🔔 Rising chime	Task completed	A background task just finished

Each sound is different so you know exactly what's happening without looking.

---

Quick Install

One-Line Install

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/whoisjaso/claude-code-ding/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/whoisjaso/claude-code-ding/main/install.ps1 | iex

Manual Install

1. Open your Claude Code user settings:

~/.claude/settings.json

2. Copy the hooks from your platform's profile into the "hooks" section:

• profiles/windows.json — Windows (PowerShell [console]::beep)
• profiles/macos.json — macOS (afplay system sounds)
• profiles/linux.json — Linux (paplay / PulseAudio)

3. Restart Claude Code or open /hooks to reload.

---

Sound Profiles

Default (Console Beeps)

Zero dependencies — uses your system's built-in beep capability. Works everywhere.

Platform	How it works
Windows	[console]::beep() via PowerShell
macOS	afplay with system sounds
Linux	paplay with freedesktop sounds

Custom Sounds

Want different sounds? Edit the commands in your settings.json hooks:

Windows — use any .wav file:

"command": "powershell -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:\\Windows\\Media\\notify.wav').PlaySync()\""

macOS — use any .aiff/.mp3 file:

"command": "afplay /System/Library/Sounds/Ping.aiff"

Linux — use any .ogg/.wav file:

"command": "paplay /usr/share/sounds/freedesktop/stereo/message-new-instant.oga"

---

How It Works

Claude Code supports hooks — shell commands that run in response to lifecycle events. claude-code-ding uses three hook events:

┌─────────────────────────────────────────────────────┐
│                   Claude Code                       │
│                                                     │
│  ┌──────────┐    PreToolUse: AskUserQuestion        │
│  │ Question │───────────────────────► 🔔 ding!      │
│  └──────────┘                                       │
│                                                     │
│  ┌──────────┐    Stop                               │
│  │ Stopped  │───────────────────────► 🔔 ding!      │
│  └──────────┘                                       │
│                                                     │
│  ┌──────────┐    TaskCompleted                      │
│  │   Done   │───────────────────────► 🔔 ding!      │
│  └──────────┘                                       │
└─────────────────────────────────────────────────────┘

• PreToolUse → AskUserQuestion — Fires right before Claude asks you something. Three quick beeps grab your attention.
• Stop — Fires whenever Claude stops generating. Two beeps signal it's your turn.
• TaskCompleted — Fires when a background task finishes. A rising chime tells you without interrupting your flow.

All hooks run with "async": true so they never block Claude's execution.

---

Configuration

Adjusting Volume & Pitch

Windows — change frequency (Hz) and duration (ms):

"command": "powershell -NoProfile -Command \"[console]::beep(800,200)\""

• First number: frequency in Hz (higher = higher pitch)
• Second number: duration in ms

macOS — adjust volume (0-255):

"command": "afplay -v 0.5 /System/Library/Sounds/Ping.aiff"

Disabling a Specific Notification

Remove or comment out the hook you don't want in ~/.claude/settings.json. For example, to keep only the "question asked" notification, remove the Stop and TaskCompleted hook entries.

Per-Project Override

Add hooks to .claude/settings.json in your project root to override global settings for that project. Set an empty hooks array to silence notifications for a specific project:

{
  "hooks": {
    "Stop": []
  }
}

---

Compatibility

Platform	Shell	Status
Windows 10/11	PowerShell 5.1+	✅ Tested
macOS 12+	zsh/bash	✅ Tested
Ubuntu 22.04+	bash	✅ Tested
Debian 12+	bash	✅ Tested
WSL2	bash	✅ Works (uses Linux profile)

Requires Claude Code (Anthropic's official CLI).

---

Troubleshooting

No sound on Linux?

Install PulseAudio utils:

sudo apt install pulseaudio-utils

Or use speaker-test as a fallback:

speaker-test -t sine -f 800 -l 1 & sleep 0.3 && kill $!

Hooks not firing?

1. Open Claude Code and type /hooks to verify hooks are loaded
2. Check ~/.claude/settings.json is valid JSON
3. Restart Claude Code — the settings watcher only detects files that existed at session start

Sound is too quiet / loud?

Adjust your system volume, or tweak the beep parameters (see Configuration).

---

Uninstall

Remove the PreToolUse (AskUserQuestion matcher), Stop, and TaskCompleted entries from the "hooks" section in ~/.claude/settings.json. Keep any other hooks you have.

Or run:

# Coming soon: uninstall script
# For now, manually edit ~/.claude/settings.json

---

FAQ

Does this work with all Claude Code versions?

Yes. Hooks are a core Claude Code feature available in all current versions. The PreToolUse, Stop, and TaskCompleted events are stable and supported.

Will this slow down Claude Code?

No. All hooks run with "async": true, meaning they execute in the background and never block Claude's response generation.

Can I use custom .wav or .mp3 files instead of beeps?

Yes! See the Custom Sounds section. Point the command to any audio file on your system.

Does this work in VS Code / Cursor / other IDEs?

Yes — Claude Code hooks work regardless of where you run Claude Code. Terminal, VS Code integrated terminal, Cursor, iTerm2, Windows Terminal — it all works.

Can I set different sounds per project?

Yes. Add a .claude/settings.json in your project root with different hook commands. Project settings override user settings.

How do I add notifications for other events?

Claude Code supports many hook events: SessionStart, PostToolUse, PreCompact, Notification, and more. Add the same command pattern to any event in your settings. See the Claude Code hooks documentation.

---

Contributing

PRs welcome! Ideas:

• More sound profiles (retro, minimal, game-like)
• Custom .wav / .ogg sound packs
• Install script improvements
• Desktop notification fallback (notify-send / osascript)
• Integration with system notification centers

---

License

MIT — do whatever you want with it.

---

Star History

If this saved you from terminal-watching, give it a ⭐

---

Stop watching your terminal. Start hearing it.
Built for the Claude Code community.