v4.0.0 - Quick Setup, Desktop Notifications & TTS

What's New

3-Tier Notification System

Tier	Name	Install	Dependencies	Features
Lite	Quick Setup	curl | bash (30s)	None	System sounds + desktop notifications
Standard	Full Install	Run installer (2min)	Python 3.6+	Custom MP3 audio + desktop notifications + context
Pro	Full + TTS	Run installer + config	Python 3.6+	Audio + notifications + context-aware TTS

Quick Setup (Lite Tier)

Zero-dependency, zero-Python, one-command setup:

curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-setup.sh | bash

• Uses platform-native commands (no Python, no MP3 files, no cloning required)
• macOS: osascript notifications with system sounds (Glass, Sosumi, Pop)
• Linux: notify-send + paplay with freedesktop sounds
• WSL/Git Bash: PowerShell system sounds and message boxes

Desktop Notifications (Full Install)

Three notification modes in config/user_preferences.json:

• audio_only — Classic behavior (backward compatible default)
• notification_only — Desktop popups only, no audio
• audio_and_notification — Both audio + desktop popups (recommended)

Context-Aware Alerts

Hook runner now parses JSON from Claude Code's stdin for rich notifications:

• Stop: "Task completed"
• Notification: "Authorization needed: Allow Bash command?"
• PreToolUse: "Running: Bash"
• SubagentStop: "Background task finished (Explore)"

Text-to-Speech (Pro Tier)

Platform-native TTS with customizable per-hook messages:

Platform	Engine
macOS	say (built-in)
Linux	espeak / spd-say
Windows/WSL	SAPI via PowerShell

Enable in config: "tts_settings": { "enabled": true }

Comparison

	DIY Hooks	Quick Setup	Full Install
Setup time	Manual JSON	30 seconds	2 minutes
Dependencies	None	None	Python 3.6+
Desktop notifications	macOS only	All platforms	All platforms
Custom MP3 audio	No	System sounds	18 professional sounds
Text-to-speech	No	No	Yes
Context-aware alerts	No	No	Yes
Debouncing	No	No	Yes
Per-hook config	No	No	Yes (9 types)

Backward Compatibility

• All existing configurations work unchanged
• Missing notification_settings defaults to audio_only
• Missing tts_settings defaults to disabled
• Quick Setup is completely independent of hook_runner.py

Files Changed

Action	File
New	scripts/quick-setup.sh — Lite tier installer
New	scripts/quick-unsetup.sh — Lite tier uninstaller
Modified	hooks/hook_runner.py — stdin parsing, notifications, TTS
Modified	config/default_preferences.json — new settings sections
Modified	config/user_preferences.json — new settings sections
Modified	README.md — restructured with Quick Setup first
Modified	CLAUDE.md — Quick Setup as first method

Full Changelog: v3.3.5...v4.0.0