{"id":41672129,"url":"https://github.com/ChanMeng666/claude-code-audio-hooks","last_synced_at":"2026-02-03T11:05:10.964Z","repository":{"id":321876262,"uuid":"1087483133","full_name":"ChanMeng666/claude-code-audio-hooks","owner":"ChanMeng666","description":"🔊 Audio notification system for Claude Code that plays sound alerts when Claude finishes responding. Perfect for multitasking!","archived":false,"fork":false,"pushed_at":"2025-12-22T11:47:44.000Z","size":3240,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-23T14:51:21.712Z","etag":null,"topics":["audio-notifications","automation","bash","claude-code","cli-tools","developer-tools","hooks","notification-system","productivity","wsl"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChanMeng666.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-01T02:12:57.000Z","updated_at":"2025-12-22T11:47:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ChanMeng666/claude-code-audio-hooks","commit_stats":null,"previous_names":["chanmeng666/claude-code-audio-hooks"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/ChanMeng666/claude-code-audio-hooks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fclaude-code-audio-hooks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fclaude-code-audio-hooks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fclaude-code-audio-hooks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fclaude-code-audio-hooks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChanMeng666","download_url":"https://codeload.github.com/ChanMeng666/claude-code-audio-hooks/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChanMeng666%2Fclaude-code-audio-hooks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29043781,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T10:09:22.136Z","status":"ssl_error","status_checked_at":"2026-02-03T10:09:16.814Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-notifications","automation","bash","claude-code","cli-tools","developer-tools","hooks","notification-system","productivity","wsl"],"created_at":"2026-01-24T18:01:51.874Z","updated_at":"2026-02-03T11:05:10.938Z","avatar_url":"https://github.com/ChanMeng666.png","language":"Shell","readme":"[![Project Banner](./public/claude-code-audio-hooks-logo.svg)](#)\n\n# Claude Code Audio Hooks 🔊\n\n\u003e **🎉 v3.3.4 Now Available!** Full Windows native support! New PowerShell installer, enhanced debug logging, and improved cross-platform compatibility!\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Version](https://img.shields.io/badge/version-3.3.4-blue.svg)](https://github.com/ChanMeng666/claude-code-audio-hooks)\n[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-green.svg)](https://github.com/ChanMeng666/claude-code-audio-hooks)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-v2.0.32%2B-brightgreen.svg)](https://claude.ai/download)\n\n---\n\nhttps://github.com/user-attachments/assets/a9919363-f76c-4dd2-9141-e1c681573d75\n\n\nhttps://github.com/user-attachments/assets/107ff48b-9d4f-40fd-9368-e36741b262ed\n\n\n\n---\n\n## 📋 Table of Contents\n\n- [What Does This Do?](#-what-does-this-do)\n- [System Architecture](#-system-architecture)\n- [Before You Start](#-before-you-start)\n- [Quick Start](#-quick-start)\n- [Installation Flow](#-installation-flow)\n- [The 9 Notification Types](#-the-9-notification-types)\n- [Hook Execution Flow](#-hook-execution-flow)\n- [Configuration](#-configuration)\n- [Testing \u0026 Verification](#-testing--verification)\n- [Audio Customization Options](#-audio-customization-options)\n- [Customization](#-customization)\n- [Upgrading from v1.0](#-upgrading-from-v10)\n- [Troubleshooting](#-troubleshooting)\n- [Uninstalling](#-uninstalling)\n- [FAQ](#-faq)\n- [Contributing](#-contributing)\n\n---\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| [**CLAUDE.md**](CLAUDE.md) | AI Assistant Guide - For Claude Code, Cursor, Copilot |\n| [**docs/ARCHITECTURE.md**](docs/ARCHITECTURE.md) | System architecture with Mermaid diagrams |\n| [**docs/INSTALLATION_GUIDE.md**](docs/INSTALLATION_GUIDE.md) | Detailed installation for all platforms |\n| [**docs/TROUBLESHOOTING.md**](docs/TROUBLESHOOTING.md) | Problem solving and debug guide |\n| [**CHANGELOG.md**](CHANGELOG.md) | Version history and release notes |\n\n---\n\n## 🎯 What Does This Do?\n\nClaude Code Audio Hooks adds **intelligent audio notifications** to Claude Code CLI. Instead of constantly watching your terminal, you'll hear pleasant voice notifications when important events occur.\n\n```mermaid\ngraph LR\n    A[User] --\u003e|Interacts with| B[Claude Code CLI]\n    B --\u003e|Triggers| C[Hook System]\n    C --\u003e|Plays| D[Audio Notifications]\n    D --\u003e|Alerts| A\n\n    style B fill:#4A90E2\n    style C fill:#7ED321\n    style D fill:#F5A623\n```\n\n**Perfect for:**\n- 💼 **Multitasking** - Work on other things while Claude processes long tasks\n- 🚨 **Authorization Alerts** - Get notified when Claude needs your permission\n- 📚 **Background Tasks** - Know when subagent tasks complete\n- ⏰ **Focus Mode** - Let audio notifications keep you informed without interrupting flow\n\n**Example Workflow:**\n1. Ask Claude to refactor a complex codebase\n2. Switch to documentation work\n3. Hear \"Task completed successfully!\" when Claude finishes\n4. If Claude needs authorization, hear \"Attention! Claude needs your authorization.\"\n5. Return to review Claude's work - no time wasted!\n\n---\n\n## 🏗️ System Architecture\n\n```mermaid\ngraph TB\n    subgraph \"Claude Code\"\n        CC[Claude Code CLI]\n    end\n\n    subgraph \"Hook System\"\n        HS[Hook Scripts\u003cbr/\u003e9 Types]\n        HC[Hook Config\u003cbr/\u003eLibrary]\n        PU[Path Utilities\u003cbr/\u003eCross-Platform]\n    end\n\n    subgraph \"Resources\"\n        AF[Audio Files\u003cbr/\u003e9 MP3s]\n        CF[Configuration\u003cbr/\u003eJSON]\n    end\n\n    subgraph \"User\"\n        U[User Terminal]\n        AS[Audio System]\n    end\n\n    CC --\u003e|Triggers| HS\n    HS --\u003e|Loads| HC\n    HC --\u003e|Uses| PU\n    HC --\u003e|Reads| CF\n    HC --\u003e|Plays| AF\n    AF --\u003e|Output| AS\n    AS --\u003e|Alerts| U\n    U --\u003e|Configures| CF\n\n    style CC fill:#4A90E2\n    style HS fill:#7ED321\n    style HC fill:#BD10E0\n    style AF fill:#F5A623\n    style AS fill:#50E3C2\n```\n\n### Key Components\n\n1. **Hook Scripts** - 9 specialized scripts that respond to different Claude Code events\n2. **Hook Config Library** - Shared functionality for all hooks (audio playback, path handling)\n3. **Path Utilities** - Cross-platform path conversion (WSL/Git Bash/Cygwin/macOS/Linux)\n4. **Audio Files** - Professional ElevenLabs voice recordings for each notification type\n5. **Configuration** - JSON-based user preferences for enabled hooks and audio files\n\n---\n\n## ✅ Before You Start\n\n### **Prerequisites:**\n\n1. **Claude Code CLI** must be installed\n   - [Download Claude Code](https://claude.ai/download) if you don't have it\n   - Verify: `claude --version`\n\n2. **Operating System:**\n   - ✅ **Windows:** Git Bash (recommended), WSL, or Cygwin\n   - ✅ **Linux:** Native Linux (Ubuntu, Debian, Fedora, Arch, etc.)\n   - ✅ **macOS:** All versions with Terminal or iTerm2\n\n3. **Optional (for manual setup):**\n   - Python 3 (for configuration management)\n   - Git (usually pre-installed)\n\n### **Platform Compatibility:**\n\n| Platform | Status | Audio Player | Installation |\n|----------|--------|--------------|--------------|\n| **Windows (Native)** | ✅ **NEW!** Full support | PowerShell | `.\\scripts\\install-windows.ps1` |\n| **WSL (Ubuntu/Debian)** | ✅ Fully tested | PowerShell | `bash scripts/install-complete.sh` |\n| **Git Bash (Windows)** | ✅ Fully supported\u003cbr/\u003e*Auto path conversion* | PowerShell | `bash scripts/install-complete.sh` |\n| **macOS** | ✅ Native support\u003cbr/\u003e*Bash 3.2+ compatible* | afplay | `bash scripts/install-complete.sh` |\n| **Native Linux** | ✅ Fully supported | mpg123/aplay | `bash scripts/install-complete.sh` |\n| **Cygwin** | ✅ Fully supported | PowerShell | `bash scripts/install-complete.sh` |\n\n\u003e **NEW in v3.3.4:** Windows users can now install directly using PowerShell - no Git Bash required!\n\n\u003e **Note for Git Bash Users:** Version 2.2+ includes automatic path conversion to handle Git Bash's Unix-style paths. The installer will configure this automatically—no manual setup required!\n\n\u003e **Note for macOS Users:** Full compatibility with macOS's default bash 3.2! All scripts have been optimized to work with the older bash version that ships with macOS. No need to install bash from Homebrew.\n\n### **Quick System Check:**\n\n```bash\n# Check if Claude Code is installed\nclaude --version\n\n# Check Python 3\npython3 --version\n\n# Check Git\ngit --version\n```\n\nIf Claude Code is missing, install it first. Other prerequisites are usually already present.\n\n---\n\n## 🚀 Quick Start\n\n### **🤖 AI-Assisted Installation** (Recommended - Zero Effort!)\n\n**Just copy this to your AI assistant (Claude Code, Cursor, Copilot, ChatGPT, etc.):**\n\n```\nPlease install Claude Code Audio Hooks version 3.3.4 from\nhttps://github.com/ChanMeng666/claude-code-audio-hooks and configure it for me.\nRun: git clone https://github.com/ChanMeng666/claude-code-audio-hooks.git \u0026\u0026 cd claude-code-audio-hooks \u0026\u0026 bash scripts/install-complete.sh\n```\n\nYour AI will handle everything automatically!\n\n---\n\n### **⚡ Quick Manual Installation** (1-2 minutes)\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/ChanMeng666/claude-code-audio-hooks.git\ncd claude-code-audio-hooks\n\n# 2. Run the complete installer (handles everything automatically!)\nbash scripts/install-complete.sh\n# The installer will:\n# - Detect your environment automatically\n# - Install all 9 hooks\n# - Configure settings and permissions\n# - Validate the installation\n# - Optionally test audio playback\n\n# 3. Restart Claude Code\n# Close and reopen your terminal\n\n# 4. Test with Claude\nclaude \"What is 2+2?\"\n# You should hear a notification when Claude finishes!\n```\n\n**That's it!** The installer automatically handles environment detection, configuration, validation, and testing.\n\n**Success Rate:** 98%+\n**Installation Time:** 1-2 minutes\n\n---\n\n### **🪟 Windows Native Installation** (PowerShell)\n\nFor Windows users who prefer not to use Git Bash:\n\n```powershell\n# 1. Clone the repository\ngit clone https://github.com/ChanMeng666/claude-code-audio-hooks.git\ncd claude-code-audio-hooks\n\n# 2. Run the PowerShell installer\n.\\scripts\\install-windows.ps1\n\n# 3. Restart Claude Code\n# Close and reopen your terminal\n\n# 4. Test with Claude\nclaude \"What is 2+2?\"\n```\n\n**Requirements:**\n- Python 3.6+ (download from python.org)\n- Claude Code CLI\n\n**Non-interactive mode:**\n```powershell\n.\\scripts\\install-windows.ps1 -NonInteractive\n```\n\n---\n\n### **🤖 Non-Interactive Installation** (For Claude Code \u0026 Automation)\n\nBoth installation and uninstallation scripts support **non-interactive mode** - perfect for Claude Code and automation!\n\n**Install without prompts:**\n```bash\n# Skips audio test prompt, completes fully automated\nbash scripts/install-complete.sh --yes\n```\n\n**Uninstall without prompts:**\n```bash\n# Auto-confirms all removals, creates backups\nbash scripts/uninstall.sh --yes\n```\n\n**Claude Code can now:**\n- ✅ Install automatically (no user input needed)\n- ✅ Uninstall automatically (no confirmations needed)\n- ✅ Configure hooks programmatically (via configure.sh CLI)\n- ✅ Fully automate setup and teardown\n\n**Options:**\n- `--yes` or `-y` - Run in non-interactive mode\n- `--help` or `-h` - Show usage documentation\n\n**Note:** Non-interactive mode is perfect for CI/CD pipelines, deployment scripts, and AI assistants like Claude Code!\n\n---\n\n## 📊 Installation Flow\n\n```mermaid\nflowchart TD\n    Start([Start Installation]) --\u003e Clone[Clone Repository]\n    Clone --\u003e Run[Run install-complete.sh]\n    Run --\u003e Detect[Detect Environment\u003cbr/\u003eWSL/Git Bash/Cygwin/macOS/Linux]\n    Detect --\u003e Check[Check Prerequisites\u003cbr/\u003eClaude Code, Python, Git]\n    Check --\u003e Install[Install 9 Hook Scripts\u003cbr/\u003eto ~/.claude/hooks/]\n    Install --\u003e Config[Configure Settings\u003cbr/\u003esettings.json \u0026 settings.local.json]\n    Config --\u003e Perms[Set Permissions\u003cbr/\u003echmod +x hooks]\n    Perms --\u003e Audio[Verify Audio Files\u003cbr/\u003e9 MP3 files]\n    Audio --\u003e Test[Run Tests\u003cbr/\u003eAutomated validation]\n    Test --\u003e Success{Success?}\n    Success --\u003e|Yes| Done([✅ Installation Complete\u003cbr/\u003eRestart Claude Code])\n    Success --\u003e|No| Diagnose[Run Diagnostics\u003cbr/\u003eCheck installation log]\n    Diagnose --\u003e Fix[Apply Fixes\u003cbr/\u003eSee Troubleshooting]\n    Fix --\u003e Test\n\n    style Start fill:#4A90E2\n    style Done fill:#7ED321\n    style Success fill:#F5A623\n    style Diagnose fill:#BD10E0\n```\n\n### **📍 Installation Locations**\n\n**Good news:** You can install this project **anywhere** on your system!\n\nThe installation script automatically records your project location, so hooks will work regardless of where you clone the repository:\n\n```bash\n# Any of these locations will work:\n~/claude-code-audio-hooks              # Home directory\n~/projects/claude-code-audio-hooks     # Projects folder\n~/Documents/claude-code-audio-hooks    # Documents\n~/repos/claude-code-audio-hooks        # Custom repos directory\n/any/custom/path/claude-code-audio-hooks  # Any path you prefer\n```\n\n**How it works:**\n1. When you run `bash scripts/install-complete.sh`, it records your project path in `~/.claude/hooks/.project_path`\n2. Hook scripts automatically find audio files and configuration using this recorded path\n3. Universal path utilities handle conversion for WSL/Git Bash/Cygwin/macOS/Linux\n4. No manual configuration needed - it just works!\n\n**Verification:**\n```bash\n# Check your recorded project path\ncat ~/.claude/hooks/.project_path\n\n# Verification is automatically performed during installation\n# If you need to check again, reinstall with:\nbash scripts/install-complete.sh\n```\n\n**Moving the project?** Just run `bash scripts/install-complete.sh` again after moving, and it will update the path automatically.\n\n---\n\n## 🎵 The 9 Notification Types\n\n### **✅ Enabled by Default (3 Essential Hooks)**\n\n```mermaid\ngraph LR\n    A[Claude Code Events] --\u003e B[Notification Hook\u003cbr/\u003e⚠️ Permission Prompts]\n    A --\u003e C[Stop Hook\u003cbr/\u003e✅ Task Complete]\n    A --\u003e D[SubagentStop Hook\u003cbr/\u003e🤖 Background Tasks]\n\n    B --\u003e E[Audio Alert]\n    C --\u003e E\n    D --\u003e E\n\n    style A fill:#4A90E2\n    style B fill:#F5A623\n    style C fill:#7ED321\n    style D fill:#BD10E0\n    style E fill:#50E3C2\n```\n\n#### **1. ⚠️ Notification Hook** - Permission Prompt Alert ⭐ KEY FEATURE\n- **When:** Claude shows \"Do you want to proceed?\" authorization prompts\n- **Audio:** \"Attention! Claude needs your authorization.\"\n- **Why enabled:** **This is the primary hook for the project's core mission!**\n- **Status:** ✅ Enabled by default\n- **Verified:** When you see permission prompts, this hook triggers and plays `notification-urgent.mp3`\n\n#### **2. ✅ Stop Hook** - Task Completion\n- **When:** Claude finishes responding to you\n- **Audio:** \"Task completed successfully!\"\n- **Why enabled:** Know when Claude is done working\n- **Status:** ✅ Enabled by default\n\n#### **3. 🤖 SubagentStop Hook** - Background Tasks\n- **When:** Background/subagent tasks complete\n- **Audio:** \"Subagent task completed.\"\n- **Why enabled:** Important for long-running operations using Task tool\n- **Status:** ✅ Enabled by default\n\n---\n\n### **❌ Disabled by Default (6 Optional Hooks)**\n\nThese hooks are available but disabled to avoid noise. Enable them in `config/user_preferences.json` if needed.\n\n#### **4. 🔨 PreToolUse Hook** - Before Tool Execution\n- **When:** Before EVERY tool (Read, Write, Edit, Bash, etc.)\n- **Audio:** \"Starting task.\"\n- **Why disabled:** Too frequent! Plays before every single tool execution\n- **Status:** ❌ Disabled by default\n\n#### **5. 📊 PostToolUse Hook** - After Tool Execution\n- **When:** After EVERY tool execution\n- **Audio:** \"Task in progress.\"\n- **Why disabled:** Extremely noisy during active development\n- **Status:** ❌ Disabled by default\n\n#### **6. 💬 UserPromptSubmit Hook** - Prompt Confirmation\n- **When:** You press Enter to submit a prompt\n- **Audio:** \"Prompt received.\"\n- **Why disabled:** Unnecessary - you already know when you submit\n- **Status:** ❌ Disabled by default\n\n#### **7. 🗜️ PreCompact Hook** - Conversation Compaction\n- **When:** Before Claude compacts conversation history\n- **Audio:** \"Information: compacting conversation.\"\n- **Why disabled:** Rare event, not critical\n- **Status:** ❌ Disabled by default\n\n#### **8. 👋 SessionStart Hook** - Session Start\n- **When:** Claude Code session starts\n- **Audio:** \"Session started.\"\n- **Why disabled:** Optional - not needed for core functionality\n- **Status:** ❌ Disabled by default\n\n#### **9. 👋 SessionEnd Hook** - Session End\n- **When:** Claude Code session ends\n- **Audio:** \"Session ended.\"\n- **Why disabled:** Optional - not needed for core functionality\n- **Status:** ❌ Disabled by default\n\n---\n\n### **Audio Frequency Guide**\n\n**Very Frequent (With default config):**\n- ✅ Stop (Every response completion)\n\n**Occasional (Few times per session):**\n- ⚠️ Notification (Permission prompts)\n- 🤖 SubagentStop (Background tasks)\n\n**If you enable optional hooks (not recommended):**\n- 🔨 PreToolUse + 📊 PostToolUse = VERY NOISY (before/after every tool!)\n- 💬 UserPromptSubmit = Noisy (every prompt)\n- 👋 SessionStart/End + 🗜️ PreCompact = Rare but unnecessary\n\n**Want to customize?** Run `bash scripts/configure.sh` for an interactive menu!\n\n---\n\n## 🔄 Hook Execution Flow\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant CC as Claude Code\n    participant HS as Hook System\n    participant AP as Audio Player\n\n    User-\u003e\u003eCC: Submit prompt\n    CC-\u003e\u003eHS: Trigger Hook Event\n\n    alt Permission Required\n        HS-\u003e\u003eAP: Play notification-urgent.mp3\n        AP--\u003e\u003eUser: 🔊 \"Attention! Authorization needed\"\n        User-\u003e\u003eCC: Grant permission\n    end\n\n    CC-\u003e\u003eCC: Process task\n\n    loop For each tool use\n        Note over HS: PreToolUse (disabled by default)\n        CC-\u003e\u003eCC: Execute tool\n        Note over HS: PostToolUse (disabled by default)\n    end\n\n    alt Background Task\n        CC-\u003e\u003eHS: SubagentStop Event\n        HS-\u003e\u003eAP: Play subagent-complete.mp3\n        AP--\u003e\u003eUser: 🔊 \"Background task completed\"\n    end\n\n    CC-\u003e\u003eHS: Stop Event\n    HS-\u003e\u003eAP: Play task-complete.mp3\n    AP--\u003e\u003eUser: 🔊 \"Task completed successfully\"\n```\n\n---\n\n## ⚙️ Configuration\n\n### **🚀 Dual-Mode Configuration Tool**\n\nThe `configure.sh` script supports **both interactive and programmatic modes** - perfect for humans AND Claude Code!\n\n#### **Interactive Mode** (Menu-Driven Interface)\n\nLaunch the interactive menu:\n\n```bash\ncd ~/claude-code-audio-hooks\nbash scripts/configure.sh\n```\n\n**Interactive Features:**\n- Toggle individual hooks on/off\n- Test audio for each hook\n- View current configuration\n- Reset to defaults\n- Save changes\n\n**Interactive Menu:**\n```\n================================================\n  Claude Code Audio Hooks - Configuration v2.0\n================================================\n\nCurrent Configuration:\n  [✓] 1. Notification     - Authorization/confirmation alerts\n  [✓] 2. Stop             - Task completion\n  [ ] 3. PreToolUse       - Before tool execution\n  [ ] 4. PostToolUse      - After tool execution\n  [ ] 5. UserPromptSubmit - Prompt submission\n  [✓] 6. SubagentStop     - Background task completion\n  [ ] 7. PreCompact       - Before conversation compaction\n  [ ] 8. SessionStart     - Session start\n  [ ] 9. SessionEnd       - Session end\n\nOptions:\n  [1-9] Toggle hook on/off\n  [T]   Test audio for specific hook\n  [R]   Reset to defaults\n  [S]   Save and exit\n  [Q]   Quit without saving\n```\n\n---\n\n#### **Programmatic Mode** (CLI Interface for Scripts \u0026 Claude Code)\n\nPerfect for automation, Claude Code, and other AI assistants!\n\n**List all hooks:**\n```bash\nbash scripts/configure.sh --list\n```\n\n**Get status of a specific hook:**\n```bash\nbash scripts/configure.sh --get notification  # Returns: true or false\n```\n\n**Enable one or more hooks:**\n```bash\nbash scripts/configure.sh --enable notification stop subagent_stop\n```\n\n**Disable hooks:**\n```bash\nbash scripts/configure.sh --disable pretooluse posttooluse\n```\n\n**Set specific values:**\n```bash\nbash scripts/configure.sh --set notification=true --set pretooluse=false\n```\n\n**Reset to recommended defaults:**\n```bash\nbash scripts/configure.sh --reset\n```\n\n**Mixed operations:**\n```bash\nbash scripts/configure.sh --enable notification --disable pretooluse session_start\n```\n\n**Show help:**\n```bash\nbash scripts/configure.sh --help\n```\n\n**Available hooks:**\n- `notification` - Authorization/confirmation requests (CRITICAL)\n- `stop` - Task completion\n- `pretooluse` - Before tool execution (can be noisy)\n- `posttooluse` - After tool execution (very noisy)\n- `userpromptsubmit` - User prompt submission\n- `subagent_stop` - Subagent task completion\n- `precompact` - Before conversation compaction\n- `session_start` - Session start\n- `session_end` - Session end\n\n**Note:** All programmatic commands automatically save changes. Remember to restart Claude Code to apply them!\n\n---\n\n### **Manual Configuration**\n\nEdit `config/user_preferences.json`:\n\n```json\n{\n  \"version\": \"2.0.0\",\n  \"enabled_hooks\": {\n    \"notification\": true,      // ⚠️ Authorization alerts\n    \"stop\": true,              // ✅ Task completion\n    \"pretooluse\": false,       // 🔨 Before tools\n    \"posttooluse\": false,      // 📊 After tools\n    \"userpromptsubmit\": false, // 💬 Prompt submission\n    \"subagent_stop\": true,     // 🤖 Subagent completion\n    \"precompact\": false,       // 🗜️ Before compaction\n    \"session_start\": false,    // 👋 Session start\n    \"session_end\": false       // 👋 Session end\n  },\n  \"audio_files\": {\n    \"notification\": \"default/notification-urgent.mp3\",\n    \"stop\": \"default/task-complete.mp3\",\n    \"pretooluse\": \"default/task-starting.mp3\",\n    \"posttooluse\": \"default/task-progress.mp3\",\n    \"userpromptsubmit\": \"default/prompt-received.mp3\",\n    \"subagent_stop\": \"default/subagent-complete.mp3\",\n    \"precompact\": \"default/notification-info.mp3\",\n    \"session_start\": \"default/session-start.mp3\",\n    \"session_end\": \"default/session-end.mp3\"\n  },\n  \"playback_settings\": {\n    \"queue_enabled\": true,     // Prevent overlapping\n    \"max_queue_size\": 5,       // Max queued sounds\n    \"debounce_ms\": 500         // Min ms between same notification\n  }\n}\n```\n\nAfter editing, restart Claude Code for changes to take effect.\n\n---\n\n## 🧪 Testing \u0026 Verification\n\nThe installation script (`install-complete.sh`) automatically performs comprehensive validation, including:\n\n1. ✅ Environment detection (WSL, Git Bash, Cygwin, macOS, Linux)\n2. ✅ Prerequisites check (Claude Code, Git, Python)\n3. ✅ Project structure validation\n4. ✅ Hook installation verification\n5. ✅ Settings configuration validation\n6. ✅ Path utilities testing\n7. ✅ Audio file verification\n\n### **Audio Playback Test**\n\nIf you skipped the audio test during installation, you can test it anytime:\n\n```bash\nbash scripts/test-audio.sh\n```\n\n**Test options:**\n1. Test all enabled hooks (recommended)\n2. Test ALL audio files (including disabled)\n3. Test specific hook\n4. Quick test (task-complete only)\n\n### **Real-World Test**\n\nTest with actual Claude Code usage:\n\n```bash\n# Simple test\nclaude \"What is 2+2?\"\n# You should hear audio when Claude finishes\n\n# Longer task\nclaude \"Explain how HTTP works in detail\"\n# You should hear audio when complete\n```\n\n---\n\n## 🎵 Audio Customization Options\n\nStarting from v2.4.0, you have **complete flexibility** in choosing your audio notifications! The project now includes **two complete audio sets**:\n\n### **🎤 Option 1: Voice Notifications (Default)**\nProfessional ElevenLabs voice recordings in `audio/default/` - perfect for clear, spoken alerts.\n\n### **🔔 Option 2: Non-Voice Chimes**\nModern UI sound effects in `audio/custom/` - ideal for users who:\n- Play music while coding\n- Prefer instrumental sounds\n- Dislike AI voices\n- Want subtle, non-intrusive notifications\n\n### **🎨 Option 3: Mixed Configuration**\nCustomize each hook individually - use chimes for some, voice for others!\n\n---\n\n### **Quick Start: Switch to Chimes**\n\nWant to use chimes instead of voice? Just copy the pre-configured example:\n\n```bash\ncd ~/claude-code-audio-hooks\n\n# Backup your current config (optional)\ncp config/user_preferences.json config/user_preferences.backup.json\n\n# Switch to all-chimes configuration\ncp config/example_preferences_chimes.json config/user_preferences.json\n\n# Test the new sounds\nbash scripts/test-audio.sh\n\n# Restart Claude Code\n# Close and reopen your terminal\n```\n\nThat's it! Now all your notifications will use modern UI chimes instead of voice.\n\n---\n\n### **Advanced: Mixed Audio Configuration**\n\nWant chimes for permission requests but voice for task completion? Use the mixed example:\n\n```bash\ncd ~/claude-code-audio-hooks\n\n# Use the mixed configuration template\ncp config/example_preferences_mixed.json config/user_preferences.json\n\n# Or customize it yourself by editing:\nnano config/user_preferences.json\n```\n\n**Example mixed configuration:**\n```json\n{\n  \"enabled_hooks\": [\"notification\", \"stop\", \"subagent\"],\n  \"audio_files\": {\n    \"notification\": \"custom/chime-notification-urgent.mp3\",  // Chime for permissions\n    \"stop\": \"default/task-complete.mp3\",                     // Voice for completion\n    \"subagent\": \"custom/chime-subagent-complete.mp3\"         // Chime for background tasks\n  }\n}\n```\n\n---\n\n### **Available Audio Files**\n\n#### **Voice Files** (`audio/default/`)\nAll narrated by Jessica voice from ElevenLabs:\n\n| File | Hook | Description |\n|------|------|-------------|\n| `notification-urgent.mp3` | notification | \"Attention! Claude needs your authorization.\" |\n| `task-complete.mp3` | stop | \"Task completed successfully!\" |\n| `subagent-complete.mp3` | subagent | \"Background task finished!\" |\n| `task-starting.mp3` | pretooluse | \"Executing tool...\" |\n| `task-progress.mp3` | posttooluse | \"Tool execution complete.\" |\n| `prompt-received.mp3` | userprompt | \"Prompt received.\" |\n| `notification-info.mp3` | precompact | \"Compacting conversation history...\" |\n| `session-start.mp3` | session_start | \"Claude Code session started.\" |\n| `session-end.mp3` | session_end | \"Session ended.\" |\n\n#### **Chime Files** (`audio/custom/`)\nModern UI sound effects:\n\n| File | Hook | Description |\n|------|------|-------------|\n| `chime-notification-urgent.mp3` | notification | Attention chime for permissions |\n| `chime-task-complete.mp3` | stop | Pleasant completion sound |\n| `chime-subagent-complete.mp3` | subagent | Background task done chime |\n| `chime-task-starting.mp3` | pretooluse | Brief startup chime |\n| `chime-task-progress.mp3` | posttooluse | Progress indicator chime |\n| `chime-prompt-received.mp3` | userprompt | Prompt acknowledgment chime |\n| `chime-notification-info.mp3` | precompact | Info notification chime |\n| `chime-session-start.mp3` | session_start | Welcome chime |\n| `chime-session-end.mp3` | session_end | Goodbye chime |\n\n---\n\n### **Configuration Examples**\n\n#### **Scenario 1: Music-Friendly Setup**\nYou play music while coding and only need alerts for permission requests:\n\n```json\n{\n  \"enabled_hooks\": [\"notification\"],\n  \"audio_files\": {\n    \"notification\": \"custom/chime-notification-urgent.mp3\"\n  }\n}\n```\n\n#### **Scenario 2: Minimal Voice**\nChimes for frequent events, voice for important completions:\n\n```json\n{\n  \"enabled_hooks\": [\"notification\", \"stop\", \"subagent\"],\n  \"audio_files\": {\n    \"notification\": \"custom/chime-notification-urgent.mp3\",\n    \"stop\": \"default/task-complete.mp3\",\n    \"subagent\": \"default/subagent-complete.mp3\"\n  }\n}\n```\n\n#### **Scenario 3: Granular Control**\nDifferent sounds for different workflow stages:\n\n```json\n{\n  \"enabled_hooks\": [\"notification\", \"stop\", \"pretooluse\"],\n  \"audio_files\": {\n    \"notification\": \"custom/chime-notification-urgent.mp3\",\n    \"pretooluse\": \"custom/chime-task-starting.mp3\",\n    \"stop\": \"default/task-complete.mp3\"\n  }\n}\n```\n\n---\n\n### **Testing Your Configuration**\n\nAfter changing audio files, test immediately:\n\n```bash\n# Test all enabled hooks\nbash scripts/test-audio.sh\n\n# Choose option 1 to test your enabled hooks\n# You'll hear each audio file play in sequence\n```\n\n**Remember:** Restart Claude Code after configuration changes!\n\n---\n\n## 🎨 Customization\n\n### **Using Custom Audio Files**\n\n#### **Option 1: Replace Default Audio**\n\n```bash\n# Copy your MP3 to the project\ncp /path/to/your-audio.mp3 ~/claude-code-audio-hooks/audio/custom/my-notification.mp3\n\n# Update configuration\nbash scripts/configure.sh\n# Or edit config/user_preferences.json manually\n```\n\n#### **Option 2: Create Audio with ElevenLabs**\n\n**ElevenLabs** provides AI text-to-speech with natural voices.\n\n**Step-by-step:**\n\n1. **Visit** https://elevenlabs.io\n2. **Sign up** for free account (free credits included)\n3. **Go to Text-to-Speech**\n4. **Choose voice** (Jessica is current default, but explore others!)\n5. **Enter text** for each notification:\n   - Notification: \"Attention! Claude needs your authorization.\"\n   - Stop: \"Task completed successfully!\"\n   - SubagentStop: \"Background task finished!\"\n   - PreToolUse: \"Executing tool...\"\n   - PostToolUse: \"Tool execution complete.\"\n   - UserPromptSubmit: \"Prompt received.\"\n   - PreCompact: \"Compacting conversation history...\"\n   - SessionStart: \"Claude Code session started.\"\n   - SessionEnd: \"Claude Code session ended.\"\n6. **Generate and download** MP3 files\n7. **Copy to project:**\n   ```bash\n   cp ~/Downloads/notification.mp3 ~/claude-code-audio-hooks/audio/custom/\n   ```\n8. **Update configuration:**\n   ```bash\n   bash scripts/configure.sh\n   ```\n\n### **Audio File Specifications**\n\n**Recommended:**\n- **Format:** MP3 (widely supported)\n- **Duration:** 2-5 seconds (notifications should be brief)\n- **Bitrate:** 128-192 kbps (balance quality and size)\n- **Sample Rate:** 44.1 kHz or 48 kHz\n- **Volume:** Normalized (consistent across files)\n\n**Tips:**\n- Keep it pleasant - you'll hear it frequently!\n- Make it noticeable but not jarring\n- Test at different system volumes\n- Shorter is better for quick notifications\n\n---\n\n## 🔄 Upgrading to v3.0\n\n### **Recommended Upgrade Method**\n\nFor the cleanest upgrade experience, we recommend uninstalling the old version and doing a fresh install:\n\n```bash\n# 1. Navigate to your project directory\ncd ~/claude-code-audio-hooks\n\n# 2. Uninstall the old version\nbash scripts/uninstall.sh\n\n# 3. Pull the latest version\ngit pull origin master\n\n# 4. Run fresh installation\nbash scripts/install-complete.sh\n\n# 5. Restart Claude Code\n# Close and reopen your terminal\n```\n\n**Why fresh install?**\n- v3.0 has a completely reorganized structure\n- Ensures no conflicts with old files\n- Takes only 1-2 minutes\n- Guarantees optimal configuration\n\n### **What's New in v3.0**\n\n- ✅ Streamlined directory structure (`scripts/internal/` for auto-run utilities)\n- ✅ Integrated environment detection (no separate scripts needed)\n- ✅ Automated validation (no manual verification needed)\n- ✅ One-command installation handles everything\n- ✅ Removed redundant scripts (simpler project structure)\n- ✅ Improved documentation (README only, no scattered docs)\n\n---\n\n## 🔧 Troubleshooting\n\n### **⚠️ Note: Upgrading from Older Versions**\n\nIf you previously installed this project (v1.x or v2.x):\n\n**Solution:** Uninstall and reinstall!\n\n```bash\ncd /path/to/claude-code-audio-hooks\nbash scripts/uninstall.sh  # Remove old version\ngit pull origin master      # Get latest code\nbash scripts/install-complete.sh  # Fresh install\n```\n\n**Why?** v3.0 has a completely reorganized structure. A fresh install ensures:\n- ✅ No conflicts with old files\n- ✅ Correct directory structure\n- ✅ Optimal configuration\n- ✅ All new features working properly\n\n---\n\n### **⚠️ Special Note for Windows Git Bash Users**\n\nIf you're using **Git Bash on Windows** and installed successfully but hear no audio, this is likely due to a **path compatibility issue** that has been **automatically fixed in v2.2+**.\n\n#### **Symptoms:**\n- Installation completes successfully\n- No errors reported\n- But audio doesn't play when Claude Code tasks finish\n- Hooks appear installed but silent\n\n#### **Quick Fix:**\n```bash\n# Re-run the installation\ncd /path/to/claude-code-audio-hooks\n\n# The installer automatically detects and fixes path issues\nbash scripts/install-complete.sh\n```\n\n#### **What was the problem?**\nGit Bash uses Unix-style paths (`/d/github_repository/...`) while Windows Python expects Windows-style paths (`D:/github_repository/...`). The hooks couldn't read configuration files due to this mismatch.\n\n#### **How we fixed it:**\nVersion 2.2+ includes automatic path conversion that:\n- Detects Git Bash environment\n- Converts paths before calling Python\n- Works transparently for all users\n- No manual configuration needed\n\n#### **Verify the fix is working:**\n```bash\n# Check hook trigger log\ncat /tmp/claude_hooks_log/hook_triggers.log\n# You should see entries like: 2025-11-06 19:35:31 | stop | task-complete.mp3\n\n# Test with Claude\nclaude \"What is 2+2?\"\n# You should hear audio when the response completes\n```\n\n---\n\n### **Issue: \"I don't hear any sound!\"**\n\n#### **Check 1: Did you restart Claude Code?**\nHooks only activate after restarting. Close and reopen your terminal.\n\n#### **Check 2: Is your audio enabled?**\n```bash\n# Check configuration\ncat ~/claude-code-audio-hooks/config/user_preferences.json\n\n# Verify enabled_hooks section\n# notification, stop, and subagent_stop should be true\n```\n\n#### **Check 3: Is the hook installed?**\n```bash\n# Check if hooks exist\nls -la ~/.claude/hooks/*_hook.sh\n\n# Re-run installation if needed\nbash scripts/install-complete.sh\n```\n\n#### **Check 4: Test audio directly**\n```bash\nbash scripts/test-audio.sh\n# Choose option 4 for quick test\n```\n\n#### **Check 5: System volume**\n- Make sure system volume isn't muted\n- Try playing other audio to verify speakers work\n- For WSL: Check both Windows and WSL volumes\n\n#### **Check 6: Audio player availability**\n\n**For WSL:**\n```bash\n# Test PowerShell\npowershell.exe -Command \"Write-Host 'PowerShell works'\"\n```\n\n**For Linux:**\n```bash\n# Install audio player\nsudo apt-get install mpg123\n\n# Test manually\nmpg123 ~/claude-code-audio-hooks/audio/default/task-complete.mp3\n```\n\n**For macOS:**\n```bash\n# Test afplay (built-in)\nafplay ~/claude-code-audio-hooks/audio/default/task-complete.mp3\n```\n\n#### **Check 7: Use the Diagnostic Tool**\n\nRun the built-in diagnostic tool to identify issues:\n\n```bash\n# Basic diagnostic\npython scripts/diagnose.py\n\n# With detailed information\npython scripts/diagnose.py --verbose\n\n# Include audio playback test\npython scripts/diagnose.py --test-audio\n\n# Full diagnostic\npython scripts/diagnose.py -v --test-audio\n```\n\nThe diagnostic tool checks:\n- Python version and platform detection\n- Hooks directory and hook_runner.py installation\n- Project path configuration\n- Audio files availability\n- Claude settings.json configuration\n- Recent hook trigger logs\n\n#### **Check 8: Enable Debug Logging**\n\nFor detailed troubleshooting, enable debug mode:\n\n**Windows (PowerShell):**\n```powershell\n$env:CLAUDE_HOOKS_DEBUG = \"1\"\nclaude \"test message\"\n# Check debug logs\nGet-Content \"$env:TEMP\\claude_audio_hooks_queue\\logs\\debug.log\"\n```\n\n**Windows (Git Bash) / macOS / Linux:**\n```bash\nexport CLAUDE_HOOKS_DEBUG=1\nclaude \"test message\"\n# Check debug logs\ncat /tmp/claude_audio_hooks_queue/logs/debug.log  # Linux/macOS\ncat \"$TEMP/claude_audio_hooks_queue/logs/debug.log\"  # Git Bash\n```\n\nDebug logs show:\n- Hook trigger events with timestamps\n- Path normalization and conversion\n- Audio file selection and playback attempts\n- Error details with stack traces\n\n### **Issue: \"Permission denied\" errors**\n\n```bash\n# Fix hook script permissions\nchmod +x ~/.claude/hooks/*.sh\nchmod +x ~/.claude/hooks/shared/hook_config.sh\n\n# Re-run installer if needed\nbash scripts/install-complete.sh\n```\n\n### **Issue: \"Installer failed\" or Python errors**\n\n```bash\n# Install Python 3\n# Ubuntu/Debian:\nsudo apt-get update\nsudo apt-get install python3\n\n# macOS:\nbrew install python3\n\n# Verify\npython3 --version\n```\n\n### **Issue: \"Hooks trigger but no audio plays\"**\n\n#### **For WSL:**\n- Verify PowerShell is accessible from WSL\n- Check Windows audio services are running\n- Try restarting Windows audio service\n\n#### **For Linux:**\n- Install mpg123: `sudo apt-get install mpg123`\n- Or install aplay: `sudo apt-get install alsa-utils`\n- Verify audio system: `pactl info`\n\n#### **For macOS:**\n- Verify afplay exists: `which afplay`\n- Check System Preferences \u003e Sound \u003e Output\n- Try: `afplay /System/Library/Sounds/Ping.aiff`\n\n### **Issue: \"Too many notifications\" (Notification spam)**\n\nThe debounce system should prevent this, but if you're getting too many:\n\n```bash\n# Configure hooks\nbash scripts/configure.sh\n\n# Disable noisy hooks:\n# - Disable PreToolUse (fires before EVERY tool)\n# - Disable PostToolUse (fires after EVERY tool)\n\n# Keep only:\n# - Notification (authorization alerts)\n# - Stop (task completion)\n# - SubagentStop (background tasks)\n```\n\n### **Issue: \"Sounds overlap/play at same time\"**\n\nThe queue system should prevent this. If it's still happening:\n\n```bash\n# Check queue settings\ncat ~/claude-code-audio-hooks/config/user_preferences.json\n\n# Ensure queue_enabled is true:\n{\n  \"playback_settings\": {\n    \"queue_enabled\": true,\n    \"max_queue_size\": 5,\n    \"debounce_ms\": 500\n  }\n}\n```\n\n### **Issue: \"Project folder moved and hooks stopped working\"**\n\nHooks look for audio files using the recorded path. If you moved the project:\n\n```bash\n# Move it back\nmv /path/to/claude-code-audio-hooks ~/\n\n# Or reinstall hooks to point to new location\ncd /path/to/claude-code-audio-hooks\nbash scripts/install-complete.sh\n```\n\n### **Still Having Issues?**\n\n1. **Run the diagnostic tool:**\n   ```bash\n   python scripts/diagnose.py -v --test-audio\n   ```\n\n2. **Check installation log:**\n   ```bash\n   # View the most recent installation log\n   # Linux/macOS:\n   ls -t /tmp/claude_hooks_install_*.log | head -1 | xargs cat\n   # Windows (PowerShell):\n   Get-Content (Get-ChildItem \"$env:TEMP\\claude_hooks_install_*.log\" | Sort-Object LastWriteTime -Descending | Select-Object -First 1)\n   ```\n\n3. **Enable debug mode and check logs:**\n   ```bash\n   export CLAUDE_HOOKS_DEBUG=1  # or $env:CLAUDE_HOOKS_DEBUG = \"1\" on PowerShell\n   claude \"test\"\n   # Then check debug.log in the logs directory\n   ```\n\n4. **Re-run installation:**\n   ```bash\n   cd ~/claude-code-audio-hooks\n   bash scripts/install-complete.sh  # Linux/macOS/Git Bash\n   # Or for Windows native:\n   # .\\scripts\\install-windows.ps1\n   ```\n\n5. **Check existing issues:** [GitHub Issues](https://github.com/ChanMeng666/claude-code-audio-hooks/issues)\n\n6. **Create new issue** with:\n   - Operating system and version\n   - Installation log content\n   - Error messages\n   - What you've already tried\n\n5. **Ask in discussions:** [GitHub Discussions](https://github.com/ChanMeng666/claude-code-audio-hooks/discussions)\n\nWe're here to help! 💙\n\n---\n\n## 🗑️ Uninstalling\n\n### **Option 1: Automated Uninstaller** (Recommended)\n\n```bash\ncd ~/claude-code-audio-hooks\nbash scripts/uninstall.sh\n```\n\n**The uninstaller will:**\n1. Remove all 9 hook scripts from `~/.claude/hooks/`\n2. Remove shared library\n3. Backup and clean `settings.json`\n4. Backup and clean `settings.local.json`\n5. Ask if you want to keep audio files\n6. Ask if you want to keep project folder\n\n**Safe process** - creates backups before any removal!\n\n### **Option 2: Manual Removal**\n\nIf you prefer manual control:\n\n```bash\n# Remove hook scripts\nrm ~/.claude/hooks/notification_hook.sh\nrm ~/.claude/hooks/stop_hook.sh\nrm ~/.claude/hooks/pretooluse_hook.sh\nrm ~/.claude/hooks/posttooluse_hook.sh\nrm ~/.claude/hooks/userprompt_hook.sh\nrm ~/.claude/hooks/subagent_hook.sh\nrm ~/.claude/hooks/precompact_hook.sh\nrm ~/.claude/hooks/session_start_hook.sh\nrm ~/.claude/hooks/session_end_hook.sh\n\n# Remove shared library\nrm -rf ~/.claude/hooks/shared/\n\n# Remove project folder\nrm -rf ~/claude-code-audio-hooks/\n```\n\n**Manual settings cleanup:**\n- Edit `~/.claude/settings.json` - Remove all hook sections\n- Edit `~/.claude/settings.local.json` - Remove hook permissions\n\nThen restart Claude Code.\n\n---\n\n## ❓ FAQ\n\n### **Q: Will this slow down Claude Code?**\n\n**A:** No! Audio plays in the background and doesn't affect Claude's performance at all. The queue and debounce systems ensure minimal overhead.\n\n### **Q: Can I use different sounds for different hooks?**\n\n**A:** Absolutely! Each of the 9 hooks can have its own audio file. Edit `config/user_preferences.json` or use `scripts/configure.sh`.\n\n### **Q: Why are some hooks disabled by default?**\n\n**A:** To prevent notification fatigue! PreToolUse and PostToolUse fire on EVERY tool execution, which can be dozens of times per Claude response. We enable only the 3 most useful hooks by default.\n\n### **Q: Can I enable all 9 hooks?**\n\n**A:** Yes, but we don't recommend it! Run `bash scripts/configure.sh` to enable any hooks you want. Be warned: PostToolUse is VERY noisy.\n\n### **Q: Does this work on macOS with the default bash?**\n\n**A:** Yes! The project is fully compatible with macOS's default bash 3.2. All scripts have been optimized to avoid bash 4+ features like associative arrays and case conversion operators. You don't need to install bash from Homebrew - the default macOS bash works perfectly.\n\n### **Q: Does this work with Claude Code's web interface?**\n\n**A:** No, this is specifically for Claude Code CLI (command-line interface). The web interface doesn't support custom hooks.\n\n### **Q: Is this safe? Will it access my data?**\n\n**A:** Completely safe! This system:\n- Only plays audio when hooks trigger\n- Doesn't collect, send, or access any data\n- Runs entirely locally on your machine\n- Is fully open source - review the code yourself\n\n### **Q: How much does this cost?**\n\n**A:** The project is **completely free and open source** (MIT License). However:\n- Claude Code itself may require a subscription\n- ElevenLabs has free credits but charges for heavy usage\n- You can use any free MP3 file instead of ElevenLabs\n\n### **Q: Can I contribute or suggest improvements?**\n\n**A:** Yes, please! We welcome:\n- Bug reports\n- Feature suggestions\n- Code contributions\n- Documentation improvements\n- Custom audio files to share\n\n### **Q: What's the difference between Stop and SubagentStop?**\n\n**A:**\n- **Stop**: Fires when Claude finishes responding to your direct prompt\n- **SubagentStop**: Fires when background/subagent tasks complete (e.g., Task tool, background searches)\n\nBoth are useful and enabled by default!\n\n### **Q: Why \"Notification\" hook instead of just using Stop?**\n\n**A:** The Notification hook specifically fires when Claude needs YOUR INPUT:\n- Authorization requests (file operations, commands)\n- Plan confirmation requests\n- Permission prompts\n\nThis is CRITICAL - you don't want to miss these! It's one of the most important features.\n\n### **Q: I'm not technical - can I still use this?**\n\n**A:** Absolutely! We have two options:\n1. **AI-Assisted Installation** - Just paste a prompt to your AI assistant (Cursor, Claude Code, Copilot, etc.) and it does everything\n2. **Manual Installation** - Copy-paste 5 commands, following our beginner-friendly guide\n\nIf you get stuck, create an issue and we'll help!\n\n### **Q: Can I use this with other Claude tools or APIs?**\n\n**A:** This is specifically designed for the official Claude Code CLI. It uses Claude Code's hooks system, which is CLI-specific. For other integrations, you'd need custom solutions.\n\n---\n\n## 📊 Project Structure\n\n```\nclaude-code-audio-hooks/\n├── hooks/                          # Hook scripts (copy to ~/.claude/hooks/)\n│   ├── notification_hook.sh        # ⚠️ Authorization alerts\n│   ├── stop_hook.sh                # ✅ Task completion\n│   ├── pretooluse_hook.sh          # 🔨 Before tool execution\n│   ├── posttooluse_hook.sh         # 📊 After tool execution\n│   ├── userprompt_hook.sh          # 💬 Prompt submission\n│   ├── subagent_hook.sh            # 🤖 Subagent completion\n│   ├── precompact_hook.sh          # 🗜️ Before compaction\n│   ├── session_start_hook.sh       # 👋 Session start\n│   ├── session_end_hook.sh         # 👋 Session end\n│   └── shared/\n│       ├── hook_config.sh          # Shared library (580 lines)\n│       ├── hook_logger.sh          # Hook logging utilities\n│       └── path_utils.sh           # Cross-platform path utilities (400+ lines)\n├── audio/\n│   ├── default/                    # 9 professional ElevenLabs voice MP3s\n│   │   ├── notification-urgent.mp3  # Authorization alert\n│   │   ├── task-complete.mp3        # Task completion\n│   │   ├── task-starting.mp3        # Tool starting\n│   │   ├── task-progress.mp3        # Tool progress\n│   │   ├── prompt-received.mp3      # Prompt submission\n│   │   ├── subagent-complete.mp3    # Subagent done\n│   │   ├── notification-info.mp3    # Info notification\n│   │   ├── session-start.mp3        # Session start\n│   │   └── session-end.mp3          # Session end\n│   └── custom/                     # 9 modern UI chime MP3s\n│       ├── chime-notification-urgent.mp3\n│       ├── chime-task-complete.mp3\n│       ├── chime-task-starting.mp3\n│       ├── chime-task-progress.mp3\n│       ├── chime-prompt-received.mp3\n│       ├── chime-subagent-complete.mp3\n│       ├── chime-notification-info.mp3\n│       ├── chime-session-start.mp3\n│       └── chime-session-end.mp3\n├── config/\n│   ├── default_preferences.json    # Default configuration template\n│   ├── user_preferences.json       # User configuration (created on install)\n│   ├── example_preferences_chimes.json  # All-chimes config example\n│   └── example_preferences_mixed.json   # Mixed audio config example\n├── scripts/\n│   ├── install-complete.sh         # Complete automated installer (v3.1+)\n│   ├── configure.sh                # Dual-mode configuration (interactive + CLI)\n│   ├── uninstall.sh                # Complete removal\n│   └── test-audio.sh               # Audio testing tool\n├── README.md                       # This file\n├── CHANGELOG.md                    # Version history\n└── LICENSE                         # MIT License\n```\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how you can help:\n\n### **Bug Reports**\nFound something not working? [Open an issue](https://github.com/ChanMeng666/claude-code-audio-hooks/issues) with:\n- Your operating system\n- Error messages from the installer\n- Contents of the installation log file (if available)\n- Steps to reproduce\n\n### **Feature Suggestions**\nHave ideas for improvements? [Open an issue](https://github.com/ChanMeng666/claude-code-audio-hooks/issues) with:\n- Clear description of the feature\n- Use cases and benefits\n- How it might work\n\n### **Code Contributions**\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n### **Documentation**\nHelp make our guides even clearer:\n- Fix typos or unclear instructions\n- Add examples or screenshots\n- Translate to other languages\n- Improve troubleshooting sections\n\n### **Share Audio Files**\nCreated great notification sounds? Share them!\n- Open a discussion with your audio files\n- Include brief descriptions\n- Specify voice/tool used (ElevenLabs, etc.)\n\n### **Spread the Word**\n- ⭐ Star this repository\n- Share with other Claude Code users\n- Write blog posts or tutorials\n- Mention us on social media\n\n---\n\n## 📜 License\n\nMIT License - You're free to use, modify, and distribute this project.\n\n**See [LICENSE](LICENSE) for full details.**\n\n---\n\n## 💝 Acknowledgments\n\n- **Anthropic** - For creating Claude Code and its extensible hooks system\n- **ElevenLabs** - For AI-powered text-to-speech technology\n- **Contributors** - Everyone who reports bugs, suggests features, and improves this project\n- **Open Source Community** - For inspiration and support\n\n---\n\n## 📬 Support \u0026 Contact\n\n- **Issues:** [GitHub Issues](https://github.com/ChanMeng666/claude-code-audio-hooks/issues)\n- **Discussions:** [GitHub Discussions](https://github.com/ChanMeng666/claude-code-audio-hooks/discussions)\n- **Repository:** [GitHub Repo](https://github.com/ChanMeng666/claude-code-audio-hooks)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n## Made with ❤️ for the Claude Code community\n\n**⭐ If this helped you, please star this repo! ⭐**\n\n**Current Version: 3.3.3** - WSL audio fix + Hooks format fix + Full automation support\n\n[Report Bug](https://github.com/ChanMeng666/claude-code-audio-hooks/issues) · [Request Feature](https://github.com/ChanMeng666/claude-code-audio-hooks/issues) · [Ask Question](https://github.com/ChanMeng666/claude-code-audio-hooks/discussions)\n\n---\n\n**One-Command Install · 95% Success Rate · AI-Autonomous · Cross-Platform · Open Source**\n\n\u003c/div\u003e\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChanMeng666%2Fclaude-code-audio-hooks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FChanMeng666%2Fclaude-code-audio-hooks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChanMeng666%2Fclaude-code-audio-hooks/lists"}