v4.7.2 - Performance Optimization: Faster Hook Execution

Performance Optimization

Optimizes hook_runner.py critical path to reduce execution overhead, especially for disabled hooks (18 of 22 by default).

Changes

• Config caching: load_config() reads disk once per invocation instead of 3× — eliminates redundant JSON parsing
• Lazy queue directory: QUEUE_DIR.mkdir() deferred from module import to first actual use
• Deferred auto-update: check_and_self_update() moved after enabled/snoozed/debounced/filtered gates — disabled hooks skip it entirely
• Context caching: get_notification_context() called once, reused for desktop notification, TTS, and webhook channels
• Webhook guard: send_webhook() only called when webhook_settings.enabled is true

Performance Impact

Scenario	Before	After	Improvement
Disabled hook	~25-35ms	~5-10ms	3-5× faster
Enabled hook (audio only)	~40-60ms	~30-45ms	~25% faster
Enabled hook (all channels)	~50-80ms	~45-70ms	~10% faster

Zero Functional Changes

All 22 hooks, all config options, all platforms, all features (audio, notifications, TTS, webhooks, Focus Flow, filters, snooze, debounce) work exactly as before. This is a pure performance optimization with no behavioral changes.

Full Changelog: v4.7.1...v4.7.2

v4.7.1 - Fix installer hang on Git Bash (Windows)

Bug Fix

Fixed: Installer hangs at step 6 ("Configuring Claude Settings") when running bash scripts/install-complete.sh on Git Bash (Windows).

Root Cause

The embedded Python script in install-complete.sh contained home_dir.replace('\', '/'). Inside a bash heredoc, \ is reduced to a single \, producing an unterminated Python string literal that silently hangs the installer.

Fix

# Before (broken in Git Bash heredoc)
hooks_dir = home_dir.replace('\', '/') + '/.claude/hooks'

# After (platform-safe, no backslash escaping needed)
hooks_dir = home_dir.replace(os.sep, '/') + '/.claude/hooks'

Affected Platforms

• Git Bash on Windows — installer would hang indefinitely at step 6
• macOS, Linux, WSL, Cygwin — not affected

Upgrade

cd claude-code-audio-hooks
git pull origin master
bash scripts/install-complete.sh

Full Changelog: v4.7.0...v4.7.1

v4.7.0 - Focus Flow: Anti-Distraction Micro-Tasks

What's New

Focus Flow turns Claude's thinking time into mindful micro-engagement. Instead of reaching for your phone while Claude processes complex tasks, a lightweight activity launches automatically — and auto-closes the moment Claude finishes.

How It Works

You submit prompt → Claude starts thinking → (15s delay) → Micro-task activates
                                                              ↓
                                              Claude finishes → Auto-closes

Available Modes

Mode	What Happens
breathing	Opens a terminal with guided breathing exercises — visual progress bars, emoji prompts, configurable patterns (4-7-8 calming, box breathing, energizing)
hydration	Desktop notification with random wellness reminders: drink water, stretch, check posture, rest eyes, or take deep breaths
url	Opens a URL in your browser (GitHub issues, Jira board, daily notes, etc.)
command	Runs any custom shell command you define

Quick Start

Add to config/user_preferences.json:

{
  "focus_flow": {
    "enabled": true,
    "mode": "breathing",
    "min_thinking_seconds": 15,
    "breathing_pattern": "4-7-8"
  }
}

Or ask Claude Code: "Enable Focus Flow with breathing exercises"

Breathing Patterns

Pattern	Description
4-7-8	Calming technique: inhale 4s, hold 7s, exhale 8s (3 cycles)
box	Navy SEAL focus technique: equal 4s phases (3 cycles)
energize	Quick energizer: fast inhale 2s, hold 2s, slow exhale 4s (4 cycles)

Design Details

• Smart delay: min_thinking_seconds (default: 15) prevents micro-tasks from flashing for quick 2-second responses
• Auto-cleanup: PID-based process management — micro-task terminal window closes automatically when Claude finishes
• Zero blocking: Focus Flow runs entirely in background processes, never slows Claude
• Marker-file state: Same proven pattern as the snooze system — no daemons, no cleanup needed

Upgrade

cd claude-code-audio-hooks
git pull origin master
bash scripts/install-complete.sh

Then restart Claude Code.

Full Changelog: v4.6.0...v4.7.0

v4.6.0 - Async Execution, Smart Matchers, Richer Context & Webhook Integration

What's New

Four major optimizations based on the official Claude Code hooks documentation — making notifications faster, smarter, more detailed, and remotely accessible.

1. Async Hook Execution

All hooks now register with "async": true. Claude Code fires hooks in the background and never waits for audio playback, eliminating 200-500ms latency per hook invocation.

No configuration needed — async is automatic for all hooks after reinstalling.

2. Smart Matchers

High-noise hooks now use Claude Code's native regex matchers to fire only for relevant tools:

Hook	Matcher	Effect
PreToolUse	Bash	Only notifies before shell commands (not Read/Glob/Grep)
PostToolUseFailure	Bash|Write|Edit	Only notifies when important tools fail

Plus a new user-configurable filters system in user_preferences.json:

"filters": {
    "posttoolusefailure": { "tool_name": "Bash|Write" },
    "subagent_start": { "agent_type_exclude": "Explore" }
}

3. Richer Notification Context

Desktop notifications now show actionable details extracted from Claude Code's JSON event data:

Before	After
"Tool failed: Bash"	"Bash failed: npm test — exit code 1"
"Running: Bash"	"Running Bash: npm install"
"Permission needed: Bash"	"Permission needed: Bash — rm -rf node_modules"

Configurable via notification_settings.detail_level: minimal, standard (default), or verbose.

4. Webhook Integration

Send notifications to external services — get Claude Code alerts on your phone, in Slack, or anywhere:

Service	Format	Use case
Slack	slack	Team channel notifications
Discord	discord	Community/team alerts
Microsoft Teams	teams	Enterprise notifications
ntfy.sh	ntfy	Free phone push notifications
Custom URL	raw	Any webhook endpoint (Zapier, IFTTT, etc.)

"webhook_settings": {
    "enabled": true,
    "url": "https://ntfy.sh/my-claude-alerts",
    "format": "ntfy",
    "hook_types": ["stop", "notification", "permission_request"]
}

Uses only Python standard library — zero additional dependencies. Runs in background threads.

Upgrade

cd claude-code-audio-hooks
git pull origin master
bash scripts/install-complete.sh

Then restart Claude Code. The installer will re-register all hooks with async execution and smart matchers.

Full Changelog: v4.5.0...v4.6.0

v4.5.0 - Full Claude Code Lifecycle Coverage (22 Hooks)

What's New

8 new hooks for complete Claude Code lifecycle coverage — up from 14 to 22 total hooks, matching every event in the official Claude Code hooks API.

New Hook Events

Hook	Purpose
StopFailure	API error notifications (rate limit, auth failure, server error)
PostCompact	Notification after context compaction completes
ConfigChange	Alert when configuration files change during a session
InstructionsLoaded	Notification when CLAUDE.md or rules files are loaded
WorktreeCreate	Alert when a worktree is created for isolated tasks
WorktreeRemove	Notification when a worktree is removed/cleaned up
Elicitation	Alert when an MCP server requests user input
ElicitationResult	Confirmation when an elicitation response is submitted

New Audio Files (16 total)

• 8 voice recordings (audio/default/) — Professional ElevenLabs Jessica voice, matching existing audio style
• 8 chime sound effects (audio/custom/) — Generated via ElevenLabs Sound Generation API

Changes

• hook_runner.py — Audio mappings, context extraction, and notification support for all 8 new hooks
• Config files — New hook entries in default_preferences.json and user_preferences.json with TTS messages
• Installers — install-complete.sh and install-windows.ps1 register all 22 hooks
• configure.sh — Interactive menu now shows all 22 hooks with descriptions
• Documentation — Comprehensive updates to CLAUDE.md, README.md, CHANGELOG.md, ARCHITECTURE.md, INSTALLATION_GUIDE.md, and TROUBLESHOOTING.md

Upgrade

cd claude-code-audio-hooks
git pull origin master
bash scripts/install-complete.sh

Then restart Claude Code.

Full Changelog: v4.4.0...v4.5.0

v4.4.0 — Snooze / Temporary Mute

Snooze / Temporary Mute (closes #7)

Temporarily silence all audio hooks for a specified duration — perfect for meetings, focus sessions, or screen sharing. Hooks auto-resume when the timer expires, no cleanup needed.

Usage

bash scripts/snooze.sh              # Snooze 30 minutes (default)
bash scripts/snooze.sh 1h           # Snooze 1 hour
bash scripts/snooze.sh status       # Check remaining time
bash scripts/snooze.sh off          # Resume immediately

Also available via configure.sh and quick-configure.sh:

bash scripts/configure.sh --snooze 1h
bash scripts/configure.sh --resume

# Lite tier (no clone needed):
curl -sL ...quick-configure.sh | bash -s -- --snooze 1h

How it works

A Unix epoch timestamp is written to a marker file in the temp directory. All hook runners (Python and Bash) check this file before playing audio — if current_time < timestamp, the hook is silently skipped. No daemon or cleanup process needed.

What's new

• scripts/snooze.sh — Standalone CLI for snooze management
• is_snoozed() check added to both hook_runner.py and hook_config.sh
• --snooze, --resume, --snooze-status flags in configure.sh
• Inline snooze commands in quick-configure.sh (works via curl | bash)
• Flexible duration formats: 30m, 1h, 2h, 90m, bare numbers, 30s
• Debug logging shows "SNOOZED" with remaining time
• Warns on >24h snooze, rejects 0 duration, handles corrupted marker files gracefully

Full Changelog: v4.3.1...v4.4.0

v4.3.1 - Quick Setup Customization

What's New

Added

• scripts/quick-configure.sh — Lightweight hook manager for Quick Setup (Lite tier) users
  • --list shows which of the 4 Quick Setup hooks are enabled/disabled
  • --disable <Hook> removes a hook from ~/.claude/settings.json
  • --enable <Hook> re-adds a hook with the correct platform-specific command
  • --only <Hook> [Hook...] keeps only the specified hooks, removes the rest
  • Works via curl | bash (no clone needed), same as quick-setup.sh
  • Case-insensitive hook name matching

Fixed

• scripts/quick-unsetup.sh now removes all 4 installed hooks including PermissionRequest (was only removing 3)

Usage

# List hooks
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --list

# Disable a noisy hook
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --disable SubagentStop

# Re-enable it
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --enable SubagentStop

# Keep only specific hooks
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --only Stop Notification

Closes #6.

Full Changelog: v4.3.0...v4.3.1

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

v4.2.2 - Robust Audio Theme Switching & Auto-Sync

What's New

Robust Audio Theme Switching

The audio_theme setting now reliably controls all 14 hooks. Previously, a hardcoded audio_files section in the config templates silently overrode the theme — switching to "custom" had no effect. This is now fixed.

Auto-Sync from Project Directory

After running git pull, the installed hook_runner.py in ~/.claude/hooks/ automatically detects the newer project version and updates itself on the next hook trigger. No manual copy needed.

configure.sh Theme Sync

Running bash scripts/configure.sh --theme custom now also copies the latest hook_runner.py to ~/.claude/hooks/, ensuring the installed copy stays current.

README: "Ask Claude Code" Quick Reference

New table in the Configuration section showing users exactly what to say to Claude Code for common tasks like switching themes and toggling hooks.

Changes

• Config templates (default_preferences.json, user_preferences.json): Removed conflicting audio_files block that overrode audio_theme
• hook_runner.py: Added HOOK_RUNNER_VERSION constant + check_and_self_update() auto-sync function + smarter get_audio_file() that ignores default template paths
• configure.sh: --theme command now syncs hook_runner.py to ~/.claude/hooks/
• README.md: Added "Ask Claude Code" table, updated config examples to use audio_theme, removed outdated audio_files examples, version bumps
• CLAUDE.md: Updated version to 4.2.2, added changelog entry

Upgrade

cd ~/claude-code-audio-hooks
git pull
# hook_runner.py will auto-sync on next hook trigger
# Or force sync now:
cp hooks/hook_runner.py ~/.claude/hooks/hook_runner.py

No reinstall needed — existing installations self-update automatically.

Full Changelog: v4.2.1...v4.2.2

v4.2.1 - Audio Theme Switching & Regenerated Chimes

What's New

Non-interactive audio theme switching and fully regenerated chime sound effects. Claude Code can now help users switch audio themes directly.

Added

• audio_theme config field — switch all 14 hooks between voice and chimes by changing one line:

  "audio_theme": "custom"

• --theme CLI command — non-interactive theme switching:

  bash scripts/configure.sh --theme custom   # chimes (no voice)
  bash scripts/configure.sh --theme default  # voice recordings

• Theme-aware audio resolution in hook_runner.py — 3-step resolution: per-hook override → audio_theme setting → fallback to default
• 14 regenerated chime sounds via ElevenLabs Sound Effects API, each with a unique character:

Chime File	Hook	Sound
chime-notification-urgent.mp3	notification	Urgent alarm, sharp rising tones
chime-task-complete.mp3	stop	Triumphant success jingle
chime-task-starting.mp3	pretooluse	Gentle activation whoosh
chime-task-progress.mp3	posttooluse	Subtle confirmation pop
chime-tool-failed.mp3	posttoolusefailure	Error descending buzzer
chime-prompt-received.mp3	userpromptsubmit	Soft bubble ping
chime-subagent-complete.mp3	subagent_stop	Achievement sparkle ding
chime-subagent-start.mp3	subagent_start	Futuristic launch whoosh
chime-notification-info.mp3	precompact	Gentle bell ding
chime-session-start.mp3	session_start	Welcoming opening melody
chime-session-end.mp3	session_end	Peaceful closing melody
chime-permission-request.mp3	permission_request	Security doorbell tone
chime-teammate-idle.mp3	teammate_idle	Sleepy standby ping
chime-team-task-done.mp3	task_completed	Team victory fanfare

How to Switch Audio

Tell Claude Code: "Switch my audio hooks to chime sounds"

Or manually:

# CLI
bash scripts/configure.sh --theme custom

# Config file (change one line)
# In config/user_preferences.json:
"audio_theme": "custom"

Custom Audio Files

Replace any MP3 in audio/default/ with your own file (keep the same filename). No config changes needed — just swap and restart Claude Code.

Full Changelog: v4.2.0...v4.2.1