v4.3.0 — Per-Hook Notification Mode Overrides

What's New

Per-hook notification mode overrides — independently control audio and desktop notifications for each hook type.

Desktop notifications queue up sequentially with delays (~5-6s each on Windows), while audio plays instantly. When many hooks fire rapidly, audio finishes in real-time but notifications keep popping up long after. Now you can set frequent hooks to audio_only while keeping critical hooks on audio_and_notification.

Added

• notification_settings.per_hook config — override the global notification mode per hook type
• disabled notification mode — suppresses both audio and desktop notifications (TTS/logging still works)
• --hook-mode CLI flag — bash scripts/configure.sh --hook-mode pretooluse=audio_only posttooluse=disabled
• Per-hook mode validation with automatic fallback to global mode on invalid values
• Comprehensive per-hook notification mode documentation in README with 7 common scenarios
• "Ask Claude Code" quick-reference table expanded with notification mode examples
• "Let Claude Code Configure It For You" guide — describe preferences in natural language

Example

{
  "notification_settings": {
    "mode": "audio_and_notification",
    "show_context": true,
    "per_hook": {
      "pretooluse": "audio_only",
      "posttooluse": "audio_only",
      "precompact": "disabled"
    }
  }
}

Mode	Audio	Desktop Popup	Notes
audio_only	✅	❌	Fast, no desktop notification delay
notification_only	❌	✅	Visual-only, no audio
audio_and_notification	✅	✅	Both channels
disabled	❌	❌	Suppresses both (TTS/logging still works)

Common Configurations

🎯 Audio for everything + desktop popups only for critical hooks (recommended):

{
  "notification_settings": {
    "mode": "audio_only",
    "per_hook": {
      "stop": "audio_and_notification",
      "notification": "audio_and_notification",
      "permission_request": "audio_and_notification"
    }
  }
}

🔕 Silence noisy hooks, keep the rest:

{
  "notification_settings": {
    "mode": "audio_and_notification",
    "per_hook": {
      "pretooluse": "disabled",
      "posttooluse": "disabled"
    }
  }
}

🤖 Let Claude Code Configure It

Just describe what you want in natural language — Claude Code reads CLAUDE.md and edits the config for you:

Scenario	What to say
Audio only, no popups	"Turn off all desktop notification popups, keep audio only"
Critical alerts only	"Only show desktop popups for task completion and authorization, audio for everything else"
Silent noisy hooks	"Disable audio and popups for pretooluse and posttooluse, they're too noisy"
Popup-only setup	"I'm in a meeting, switch everything to desktop notifications only, no audio"
Full awareness	"Enable both audio and desktop popups for all hooks"

Upgrade

No reinstall needed — existing installations self-update automatically on the next hook trigger after git pull. The per_hook field is fully backward compatible: if absent, all hooks use the global mode as before.

cd ~/claude-code-audio-hooks
git pull

Full Changelog: https://github.com/ChanMeng666/claude-code-audio-hooks/blob/master/CHANGELOG.md