🔔 ClaudeNotification

Stop babysitting your Claude Code runs. Get a soft chime and a clean popup the moment Claude needs your input, asks for permission, or finishes a task — so you can walk away and get pulled back exactly when it matters.

---

Claude Code can already notify you… if Windows toasts are enabled. Turn Windows notifications off — like a lot of people do — and every toast silently vanishes. You go make coffee, come back twenty minutes later, and Claude has been sitting there waiting for a single yes/no the whole time.

ClaudeNotification fixes that. It checks whether toasts actually work and, when they don't, falls back to a lightweight popup window that shows up no matter what your Windows settings say — with a soft, synthesized chime so you hear it even when you're heads-down in something else.

✨ Features

• 🧠 Smart backend — native Windows toast when it works, a focus-safe popup when it doesn't. Decided automatically at runtime.
• 🎯 Never steals focus — appears top-most in the corner without yanking you out of a fullscreen video or game.
• 🎵 Soft procedural chime — a gentle two-note sine tone, synthesized from scratch (no harsh system beep). Reshape the pitch, volume, and tail in one line.
• 🔔 Two triggers — "needs your input / permission" and "finished the turn."
• 🛟 Non-destructive installer — merges into your existing settings.json without touching anything else, backs it up first, and is safe to re-run.
• 🧹 One-command uninstall.

🚀 Quick start

git clone https://github.com/akinalpfdn/ClaudeNotification.git
cd ClaudeNotification
powershell -ExecutionPolicy Bypass -File .\install.ps1

Restart Claude Code (or open /hooks once) so the hooks load — you'll get a test ping right away. That's it.

Install options

Command	Effect
install.ps1	Install / update (idempotent)
install.ps1 -Mode toast	Force a backend: auto (default), toast, or popup
install.ps1 -NoSound	Install without the chime
install.ps1 -Force	Also flip disableAllHooks: true → false if it's set
install.ps1 -Uninstall	Remove the hooks and installed files

⚙️ Configuration

The installer drops a config.json in ~/.claude/claude-notification/. Edit it any time:

Key	Default	Meaning
mode	"auto"	auto | toast | popup
sound	true	Play the chime
durationSeconds	4.5	How long the popup stays on screen
accentColor	"#40C4FF"	Popup accent bar + title color
title	"Claude Code"	Notification title

🎚️ Make the sound yours

The chime is generated by gen-sound.ps1 — re-run it with different parameters to reshape it:

# softer, lower, longer tail
powershell -File "$env:USERPROFILE\.claude\claude-notification\gen-sound.ps1" -Amp 0.12 -Freq1 440 -Freq2 587 -Decay 2.5

Param	Meaning
-Amp	Loudness (0–1); lower = softer
-Freq1 / -Freq2	The two note pitches (Hz)
-Decay	Higher = shorter, tighter tail

🛠️ How it works

ClaudeNotification registers two Claude Code hooks in ~/.claude/settings.json:

Hook	Fires when
Notification	Claude needs input or permission
Stop	Claude finishes a turn

Both call claude-notify.ps1, which reads the hook's JSON payload, decides toast vs popup, plays the chime, and shows the alert. Hooks run async so they never block your session, and every error is swallowed so a hook can't break Claude Code.

🧹 Uninstall

powershell -ExecutionPolicy Bypass -File .\install.ps1 -Uninstall

Removes only our hooks (leaving the rest of your settings untouched) and deletes the installed folder.

🩺 Troubleshooting

No notification at all?

1. Restart Claude Code — hooks load at startup, and a new chat does not reload them. Or open /hooks once.
2. Make sure disableAllHooks isn't true in ~/.claude/settings.json (re-run install with -Force to fix).
3. In /hooks, confirm Notification and Stop each list a hook.

The "Task done" popup fires on every turn — that's by design (Stop fires whenever Claude finishes). To silence just that one, delete the Stop block from your settings.json hooks section; the input/permission ping keeps working.

Only the toast fails — your Windows toasts are off. Set "mode": "popup" in config.json and you'll always get the popup.

🌍 Cross-platform?

v1 is Windows-only (PowerShell + WinForms). macOS/Linux support is welcome — see DECISIONS.md for the rationale. PRs appreciated.

💛 Contributing

Found a bug, want a new sound preset, or a -NoStop flag? Open an issue or a PR. If this saved you from staring at an idle terminal, a ⭐ helps others find it.

📄 License

MIT © 2026 akinalpfdn