Skip to content

Latest commit

 

History

History
561 lines (448 loc) · 22.6 KB

CHANGELOG.md

File metadata and controls

561 lines (448 loc) · 22.6 KB

Changelog

All notable changes to Claude Code Audio Hooks will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[3.3.4] - 2025-12-22

🪟 Full Windows Native Support & Cross-Platform Improvements

This release adds comprehensive Windows native support and improves cross-platform compatibility across all environments.

Added

1. Windows PowerShell Installer (scripts/install-windows.ps1)

  • New: Native PowerShell installer for Windows users who don't use Git Bash
  • Features:
    • Prerequisite checking (Python 3.6+, Claude Code CLI)
    • Automatic settings.json configuration
    • Installation validation and testing
    • Non-interactive mode (-NonInteractive flag)

2. Diagnostic Tool (scripts/diagnose.py)

  • New: Cross-platform diagnostic utility for troubleshooting
  • Checks:
    • Python version and platform detection (Windows/WSL/macOS/Linux/Git Bash)
    • Hooks directory and hook_runner.py installation status
    • Project path configuration and audio files availability
    • Claude settings.json hook configuration
    • Recent hook trigger logs
  • Options: --verbose for detailed info, --test-audio to test playback

3. Debug Logging Mode

  • New: Set CLAUDE_HOOKS_DEBUG=1 environment variable to enable detailed logging
  • Logs include: Hook triggers, path normalization, audio playback attempts, errors
  • Log location: $TEMP/claude_audio_hooks_queue/logs/debug.log (Windows) or /tmp/claude_audio_hooks_queue/logs/debug.log (Unix)

Improved

1. Enhanced hook_runner.py

  • Path Normalization: Handles Git Bash (/d/...), WSL2 (/mnt/c/...), and Cygwin (/cygdrive/c/...) paths
  • PowerShell Safety: Proper escaping of special characters in audio file paths
  • Temp Directory: Cross-platform temp directory detection with multiple fallbacks
  • Error Handling: Granular exception handling with detailed error logging
  • Debug Output: Comprehensive logging when CLAUDE_HOOKS_DEBUG=1 is set

2. Improved install-complete.sh

  • Temp Directory: Uses platform-appropriate temp directories ($TEMP on Windows, /tmp on Unix)
  • Path Format: Saves .project_path in Windows format on Windows environments
  • Python Detection: Prioritizes py launcher on Windows, then python3, then python

3. Updated hook_config.sh

  • Debug Logging: Added log_debug() and log_error() functions
  • Temp Directory: Cross-platform temp directory handling
  • Path Functions: Unified path conversion with hook_runner.py

Cross-Platform Status

  • ✅ Windows Native: Full support via PowerShell installer
  • ✅ Windows + Git Bash: Automatic path conversion
  • ✅ Windows + WSL: PowerShell audio playback via temp file copy
  • ✅ macOS: Full support (afplay)
  • ✅ Linux: Full support (mpg123/ffplay/aplay)
  • ✅ Cygwin: Full support with path conversion

Upgrade Instructions

For existing installations:

cd claude-code-audio-hooks
git pull origin master

# Re-run installer to update all components
bash scripts/install-complete.sh  # Linux/macOS/Git Bash
# Or: .\scripts\install-windows.ps1  # Windows PowerShell

To enable debug logging:

export CLAUDE_HOOKS_DEBUG=1  # Linux/macOS/Git Bash
# Or: $env:CLAUDE_HOOKS_DEBUG = "1"  # Windows PowerShell

[3.3.3] - 2025-11-07

🐛 Critical Bug Fixes: WSL Audio & Hooks Format

This release fixes two critical issues affecting WSL users and new installations.

Fixed

1. WSL Audio Playback Issue

  • Problem: Windows MediaPlayer could not access audio files via WSL UNC paths (\\wsl.localhost\...)
  • Solution: Audio files are now copied to Windows temp directory (C:/Windows/Temp) before playback
  • Impact: WSL users can now hear audio notifications correctly
  • Technical Details:
    • Modified play_audio_internal() in hooks/shared/hook_config.sh
    • Automatic cleanup after playback completes
    • Increased playback wait time from 3s to 4s for reliability
    • Background process handles file cleanup to avoid blocking

2. Hooks Format Compatibility (Credits: @PaddyPatPat)

  • Problem: Installer generated deprecated hooks format, causing Claude Code v2.0.32+ to report "Invalid Settings"
  • Solution: Updated installer to generate new array-based format required by Claude Code v2.0.32+
  • Impact: New installations now work correctly with latest Claude Code
  • Technical Details:
    • Modified scripts/install-complete.sh Python script
    • Old format: "Notification": "~/.claude/hooks/notification_hook.sh"
    • New format: "Notification": [{"hooks": [{"type": "command", "command": "~/.claude/hooks/notification_hook.sh"}]}]
    • Each hook now formatted as array of matcher objects

Cross-Platform Status

  • ✅ WSL users: Both audio playback and hooks format fixed
  • ✅ macOS users: No changes (continues using afplay)
  • ✅ Linux users: No changes (continues using mpg123/aplay)
  • ✅ Git Bash users: No changes (already working)

Upgrade Instructions

For existing installations:

cd claude-code-audio-hooks
git pull origin master

# Update hook audio playback
cp hooks/shared/hook_config.sh ~/.claude/hooks/shared/hook_config.sh

# Re-run installer to update hooks format
bash scripts/install-complete.sh

Credits

  • WSL audio fix: Main development team
  • Hooks format fix: Special thanks to @PaddyPatPat for identifying and documenting the hooks format issue in PR #2

[3.3.2] - 2025-11-07

Note

This version was superseded by v3.3.3 which includes additional hooks format fix. Please upgrade to v3.3.3.

[3.3.1] - 2025-11-06

🐛 Critical Bug Fixes: Installation Script Stability

Fixed critical issues preventing successful installation on WSL and other platforms.

Fixed

  • Bash arithmetic expression error with set -e:

    • Replaced post-increment operators (++) with compound assignment (+=1)
    • Post-increment returns 0 when variable is 0, causing set -e to exit
    • Affected counters: STEPS_COMPLETED, WARNINGS, ERRORS, and all test counters
    • Installation now completes successfully on all platforms

  • Python type error in configuration validation:

    • Fixed TypeError: unsupported operand type(s) for +: 'int' and 'str'
    • Configuration validation now filters out comment keys (starting with _)
    • Properly handles JSON files with inline comments

Impact

  • ✅ Installation now works reliably on WSL
  • ✅ All arithmetic operations safe with set -e
  • ✅ Configuration validation handles commented JSON
  • ✅ No breaking changes - fully backward compatible

Technical Details

# Before (fails with set -e when var=0)
((STEPS_COMPLETED++))

# After (works correctly)
((STEPS_COMPLETED+=1))

[3.3.0] - 2025-11-06

🤖 Full Automation Support: Non-Interactive Mode for All Scripts

All core scripts (install-complete.sh, uninstall.sh, configure.sh) now support non-interactive mode - enabling complete automation by Claude Code and scripts!

Added

  • Non-interactive mode for install-complete.sh:

    • --yes/-y/--non-interactive - Skip audio test prompt
    • --help - Show comprehensive usage guide
    • Auto-completes installation without user input

  • Non-interactive mode for uninstall.sh:

    • --yes/-y/--non-interactive - Auto-confirm all removals
    • --help - Show comprehensive usage guide
    • Automatically removes: hooks, settings, config, audio files
    • Creates backups before deletion
    • Zero prompts, full automation

Changed

  • Version updates:
    • install-complete.sh → v3.2.0
    • uninstall.sh → v3.2
    • Added version info in script headers

Enhanced

  • Complete Claude Code Automation - AI assistants can now:

    • Install without prompts: bash install-complete.sh --yes
    • Uninstall without prompts: bash uninstall.sh --yes
    • Configure hooks: bash configure.sh --enable notification
    • Fully automate entire lifecycle

  • CI/CD Ready:

    • Perfect for deployment pipelines
    • Scriptable setup and teardown
    • No TTY required

Impact

  • ✅ 100% non-interactive capability across all scripts
  • ✅ Claude Code can fully automate install/uninstall/configure
  • ✅ Zero user input required for automation
  • ✅ Backward compatible - interactive mode still default

Examples

# Full automated installation
bash scripts/install-complete.sh --yes

# Full automated uninstallation
bash scripts/uninstall.sh --yes

# Configure hooks programmatically
bash scripts/configure.sh --enable notification stop --disable pretooluse

[3.2.0] - 2025-11-06

🤖 Major Enhancement: Dual-Mode Configuration Tool

configure.sh now supports both human-friendly interactive mode AND programmatic CLI interface - making it usable by Claude Code, scripts, and automation tools!

Added

  • Programmatic CLI Interface for configure.sh:
    • --list - List all hooks and their status
    • --get <hook> - Get status of specific hook (returns true/false)
    • --enable <hook> [hook2...] - Enable one or more hooks
    • --disable <hook> [hook2...] - Disable one or more hooks
    • --set <hook>=<value> - Set hook to specific value
    • --reset - Reset to recommended defaults
    • --help - Show comprehensive usage guide
  • Batch Operations - Enable/disable multiple hooks in one command
  • Idempotent Operations - Safe to run multiple times, only changes what's needed
  • Clear Output - Visual indicators (✓/✗) for all operations

Changed

  • configure.sh is now a dual-mode tool:
    • No arguments → Interactive menu (existing functionality preserved)
    • With arguments → Programmatic CLI (new functionality)
  • All programmatic commands automatically save changes
  • Error handling for unknown hooks (warnings, not failures)

Enhanced

  • AI Assistant Integration - Claude Code and other AI tools can now:
    • Query hook configuration programmatically
    • Enable/disable hooks based on user preferences
    • Automate configuration setup
  • Script Automation - Easy to integrate into deployment scripts
  • Backward Compatible - Interactive mode works exactly as before

Impact

  • ✅ Claude Code can now configure hooks!
  • ✅ Scriptable configuration - No more manual editing needed
  • ✅ Batch operations - Change multiple hooks at once
  • ✅ 100% backward compatible - Existing users unaffected

Examples

# Check if notification hook is enabled
bash scripts/configure.sh --get notification

# Enable multiple hooks at once
bash scripts/configure.sh --enable notification stop subagent_stop

# Mixed operations in one command
bash scripts/configure.sh --enable notification --disable pretooluse

[3.1.1] - 2025-11-06

🧹 Deep Cleanup: Removing All Redundant Scripts

Further simplification by removing truly unnecessary internal scripts and fixing broken references. Now only essential, actively-used files remain.

Removed

  • scripts/internal/detect-environment.sh (25KB) - Completely redundant
    • Environment detection already integrated in hooks/shared/path_utils.sh
    • Never actually called - only mentioned in log messages
    • Removed entire /scripts/internal/ directory (now empty)
  • scripts/.internal-tests/check-setup.sh (8.3KB) - Unused diagnostic script
    • Not called by install-complete.sh
    • Had broken path references in test-audio.sh
  • scripts/.internal-tests/test-path-conversion.sh (5.7KB) - Never invoked
    • No script in the entire project calls it
    • Pure legacy code

Fixed

  • Broken references in test-audio.sh:
    • Removed reference to non-existent ./scripts/check-setup.sh
    • Removed reference to non-existent docs/AUDIO_CREATION.md
    • Updated to point users to installer and README.md
  • Misleading suggestions in install-complete.sh:
    • Removed suggestions to manually run detect-environment.sh
    • Replaced with advice to re-run installer

Changed

  • scripts/.internal-tests/ now contains only 1 file:
    • test-path-utils.sh (8.7KB) - The ONLY test script actually used by installer
    • Everything else eliminated

Impact

  • ✅ ~39KB of truly redundant code removed (detect-environment.sh + unused tests)
  • ✅ Zero broken references - All documentation now accurate
  • ✅ Ultra-minimal structure - Only files that are actually used
  • ✅ No duplicate functionality - Environment detection in one place only

[3.1.0] - 2025-11-06

🎯 Project Cleanup: Achieving True Single-Installation Simplicity

This release further streamlines the project structure by removing unnecessary files and hiding internal utilities from users. The goal: users clone and run ONE installation command, with ZERO confusion.

Removed

  • Deleted /examples/ directory - Redundant with /config/ directory
    • Removed outdated v1.0 example files
    • Eliminated duplicate configuration examples
    • Configuration examples now only in /config/
  • Deleted /docs/ directory - Empty directory, all docs consolidated in README.md
  • Deleted obsolete patch script - scripts/internal/apply-windows-fix.sh
    • v2.x legacy patch script no longer needed
    • All fixes now integrated into install-complete.sh
  • Removed personal development files - Added .claude/ to .gitignore

Changed

  • Hidden internal test scripts - Renamed /scripts/tests/ → /scripts/.internal-tests/
    • Test scripts are auto-run by installer, users shouldn't see them
    • Reduces decision paralysis and confusion
    • Updated all internal references to new path
  • Simplified documentation references
    • Removed suggestions to manually run internal scripts
    • Updated bug report template to request log files instead
    • Simplified project structure diagram
  • Cleaner visible file structure
    • From 7 top-level directories → 5 directories
    • From 21+ visible files → ~15 essential files
    • Only user-facing scripts visible in /scripts/

Impact

  • ✅ Zero decision anxiety - One clear installation path
  • ✅ Reduced confusion - No unnecessary files or scripts visible
  • ✅ Cleaner project - ~4,100 lines of redundant code removed
  • ✅ Better UX - Users focus on: Clone → Install → Use

[3.0.1] - 2025-11-06

Fixed

  • Uninstall Script: Fixed bash syntax error on line 115 where local keyword was incorrectly used outside function scope

[3.0.0] - 2025-11-06

🎯 Major Release: Streamlined Installation & Zero-Redundancy Project Structure

This release focuses on simplifying the user experience by consolidating all installation, validation, and testing into a single streamlined workflow. Users no longer need to run multiple scripts or worry about patches and upgrades.

Added

  • Integrated Installation Workflow: install-complete.sh now automatically:
    • Detects environment (WSL, Git Bash, Cygwin, macOS, Linux)
    • Applies platform-specific fixes automatically
    • Validates installation with comprehensive tests
    • Offers optional audio testing at the end
    • All in one smooth, automated process
  • Organized Directory Structure:
    • scripts/internal/ - Internal tools auto-run by installer (users don't need to know about these)
    • scripts/tests/ - Testing tools auto-run by installer (users don't need to run manually)
  • Interactive Audio Testing: Installer now asks if users want to test audio playback
  • Comprehensive Validation: Automated 5-point validation during installation

Changed

  • Simplified Installation: From 6 manual steps down to 1 command
    • Before v3.0: Clone → Install → Verify → Test → Configure → Restart
    • v3.0: Clone → Install (everything else automatic) → Restart
  • Success Rate Improvement: From 95% to 98%+ due to integrated diagnostics
  • Installation Time: Reduced from 2-5 minutes to 1-2 minutes
  • Upgrade Method: Now recommends uninstall + fresh install instead of upgrade scripts
    • Simpler, cleaner, no conflicts with old structure
    • Takes only 1-2 minutes
    • Guarantees optimal configuration

Removed (Streamlining)

  • Redundant Scripts:
    • ❌ install.sh - Replaced by enhanced install-complete.sh
    • ❌ upgrade.sh - Users should uninstall + reinstall for v3.0
    • ❌ Manual check-setup.sh runs - Now auto-runs during installation
    • ❌ Manual detect-environment.sh runs - Now integrated into installer
    • ❌ Manual path testing - Now automatic during installation
  • Redundant Documentation:
    • Removed scattered .md files (AI_INSTALL.md, UTILITIES_README.md, etc.)
    • Everything now in README.md only
    • Cleaner, more maintainable documentation

Relocated (Better Organization)

  • scripts/detect-environment.sh → scripts/internal/detect-environment.sh
  • scripts/apply-windows-fix.sh → scripts/internal/apply-windows-fix.sh
  • scripts/check-setup.sh → scripts/tests/check-setup.sh
  • scripts/test-path-utils.sh → scripts/tests/test-path-utils.sh
  • scripts/test-path-conversion.sh → scripts/tests/test-path-conversion.sh

Enhanced

  • install-complete.sh v3.0 (was v2.1):
    • Integrated environment detection
    • Automatic platform-specific fixes
    • Comprehensive validation (7 checks)
    • Interactive audio testing option
    • Better error reporting and troubleshooting guidance
  • README.md:
    • Updated to v3.0 with accurate script references
    • Simplified installation instructions
    • Removed references to deleted scripts
    • Updated troubleshooting section
    • Clearer upgrade instructions
    • Accurate project structure diagram

User Benefits

  • ✅ One-Command Installation: Everything handled automatically
  • ✅ No Manual Testing Required: Installer validates everything
  • ✅ No Patches Needed: All fixes applied automatically
  • ✅ Cleaner Project: Only essential user-facing scripts remain
  • ✅ Better Documentation: Single source of truth (README.md)
  • ✅ Faster Installation: 1-2 minutes vs 2-5 minutes
  • ✅ Higher Success Rate: 98%+ vs 95%

Breaking Changes

  • Directory structure changed: Old scripts moved to internal/ and tests/
  • Removed scripts: Users upgrading from v2.x should uninstall first, then install v3.0
  • No upgrade.sh: Fresh install recommended for cleanest experience

Migration Guide

For users upgrading from v2.x or earlier:

cd ~/claude-code-audio-hooks
bash scripts/uninstall.sh  # Remove old version
git pull origin master      # Get v3.0
bash scripts/install-complete.sh  # Fresh install

Technical Details

  • Version: 3.0.0
  • Scripts reorganized: 11 scripts → 4 user-facing + 5 internal/test scripts
  • Installation steps: 11 automated steps (up from 10)
  • Total lines of code: Reduced by removing redundancy
  • Success rate: 98%+
  • Installation time: 1-2 minutes

[2.4.0] - 2025-11-06

Added

  • Dual Audio System: Complete flexibility to choose between voice and non-voice notifications
    • 9 new modern UI chime sound effects in audio/custom/ directory
    • 9 refreshed voice notifications in audio/default/ directory (Jessica voice from ElevenLabs)
  • Pre-configured Examples:
    • config/example_preferences_chimes.json - All chimes configuration
    • config/example_preferences_mixed.json - Mixed voice and chimes with scenario templates
  • Audio Customization Documentation: New comprehensive section in README explaining:
    • Three audio options (voice-only, chimes-only, mixed)
    • Quick-start guide for switching to chimes
    • Available audio files comparison table
    • Configuration scenarios for different use cases
  • User Choice Philosophy: System now supports complete user customization
    • Default configuration uses voice (existing behavior preserved)
    • Users can easily switch to chimes or create mixed configurations
    • Simple one-file configuration change to switch audio sets

Changed

  • README.md updated with new "Audio Customization Options" section
  • Version badges updated to v2.4.0
  • Table of Contents updated with new audio customization section

Enhanced

  • User flexibility: Users can now choose audio style based on personal preference
  • Music-friendly option: Chimes don't interfere with background music
  • Mixed configurations: Different audio types for different notification priorities

Background

This release addresses user feedback requesting non-voice notification options, particularly for users who:

  • Play music while coding
  • Prefer instrumental sounds over AI voices
  • Want different audio styles for different notification types

The dual audio system maintains backward compatibility (default voice notifications) while providing complete flexibility for users who want alternatives.

[2.3.1] - 2025-11-06

Fixed

  • Critical bug in configure.sh save_configuration() function that prevented saving on macOS
  • Python heredoc in configure.sh now correctly passes CONFIG_FILE path using shell variable substitution
  • Resolved IndexError when accessing sys.argv[1] in Python heredoc

[2.3.0] - 2025-11-06

Added

  • Full compatibility with macOS default bash 3.2
  • Bash version detection in install.sh with helpful warnings
  • Compatibility notes in scripts for macOS users

Fixed

  • Replaced bash 4+ associative arrays with indexed arrays in configure.sh and test-audio.sh
  • Replaced bash 4+ case conversion operators (${var^^} and ${var,,}) with tr commands in path_utils.sh
  • All scripts now work with bash 3.2+ without requiring Homebrew bash on macOS

Changed

  • Refactored configure.sh to use parallel indexed arrays instead of associative arrays
  • Refactored test-audio.sh to use parallel indexed arrays for configuration data
  • Updated path_utils.sh to use portable tr command for case conversion
  • Enhanced README with macOS compatibility information

[2.2.0] - Previous Release

Added

  • Automatic format compatibility for Claude Code v2.0.32+
  • Git Bash path conversion fixes
  • Enhanced Windows compatibility

Fixed

  • Path conversion issues on Git Bash
  • Audio playback on various Windows environments

[2.1.0] - Previous Release

Added

  • Hook trigger logging system
  • Diagnostic tools for troubleshooting
  • View-hook-log.sh script for monitoring hook triggers

[2.0.0] - Major Release

Added

  • 9 different hook types (up from 1 in v1.0)
  • Professional ElevenLabs audio files
  • Interactive configuration tool
  • JSON-based user preferences
  • Audio queue system
  • Debounce system
  • Automatic v1.0 upgrade support

Changed

  • Complete project restructure
  • Modular hook system with shared library
  • Cross-platform support improvements

[1.0.0] - Initial Release

Added

  • Basic stop hook with audio notification
  • Simple installation script
  • Custom audio support