{"id":32696199,"url":"https://github.com/chanmeng666/claude-code-audio-hooks","last_synced_at":"2026-05-01T12:02:05.003Z","repository":{"id":321876262,"uuid":"1087483133","full_name":"ChanMeng666/claude-code-audio-hooks","owner":"ChanMeng666","description":"【Stars make the code shine brighter!⭐️】🔊 Audio notification system for Claude Code that plays sound alerts when Claude finishes responding. Perfect for multitasking!","archived":false,"fork":false,"pushed_at":"2026-04-11T03:03:23.000Z","size":4880,"stargazers_count":41,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-11T03:13:07.318Z","etag":null,"topics":["audio-notifications","automation","bash","claude-code","cli-tools","developer-tools","hooks","notification-system","productivity","wsl"],"latest_commit_sha":null,"homepage":"https://github.com/user-attachments/assets/3504d214-efac-4e01-84c0-426430b842d6","language":"Python","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":"2026-04-11T03:03:27.000Z","dependencies_parsed_at":"2026-02-17T01:00:29.999Z","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":33,"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":31670383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2025-11-01T19:00:41.562Z","updated_at":"2026-05-01T12:02:04.986Z","avatar_url":"https://github.com/ChanMeng666.png","language":"Python","funding_links":["https://buymeacoffee.com/chanmeng66u"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\u003ca name=\"readme-top\"\u003e\u003c/a\u003e\n\n[![Project Banner](./public/claude-code-audio-hooks-logo.svg)](#)\n\n# Claude Code Audio Hooks\n\n**AI-operated audio notification system for Claude Code \u0026 Cursor IDE.**\u003cbr/\u003e\nYou type one slash command at install time. Then natural language forever.\u003cbr/\u003e\n26 hook events, 2 audio themes, rate-limit alerts, webhooks, TTS, context monitor — all operated by Claude Code on your behalf.\u003cbr/\u003e\n**🆕 5.1.5 — Painless upgrades.** Existing users never lose config across upgrades. New `audio-hooks upgrade` wraps `claude plugin update` / `uninstall + install` with `--keep-data` automatically; auto-migration preserves your settings when new keys are added in future versions; dual-location backups survive even rough `claude plugin uninstall`. Run it any time you want to refresh the plugin code Cursor's bridge invokes. See [CHANGELOG](./CHANGELOG.md#515---2026-05-01).\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-5.1.5-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.1.80%2B-brightgreen.svg)](https://claude.ai/download)\n[![Plugin](https://img.shields.io/badge/install-just_talk_to_Claude-purple.svg)](#-install-in-60-seconds)\n\n**Share This Project**\n\n[![][share-x-shield]][share-x-link]\n[![][share-linkedin-shield]][share-linkedin-link]\n[![][share-reddit-shield]][share-reddit-link]\n[![][share-telegram-shield]][share-telegram-link]\n[![][share-whatsapp-shield]][share-whatsapp-link]\n\n---\n\n### Promotional Video\n\nhttps://github.com/user-attachments/assets/3504d214-efac-4e01-84c0-426430b842d6\n\n\u003csup\u003eBuilt with Remotion, Claude Code, ElevenLabs \u0026 Suno. Source: \u003ca href=\"https://github.com/ChanMeng666/claude-code-audio-hooks-promo-video\"\u003eclaude-code-audio-hooks-promo-video\u003c/a\u003e\u003c/sup\u003e\n\n\u003c/div\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003eTable of Contents\u003c/kbd\u003e\u003c/summary\u003e\n\n- [What's New in v5.0](#-whats-new-in-v50)\n- [Install in 60 Seconds](#-install-in-60-seconds)\n- [Just Say It — Natural Language Control](#-just-say-it--natural-language-control)\n- [How It Works](#-how-it-works)\n- [Key Features](#-key-features)\n- [Technical Reference](#-technical-reference)\n- [Platform Support](#-platform-support)\n- [Troubleshooting](#-troubleshooting)\n- [Uninstall](#-uninstall)\n- [For Developers](#-for-developers)\n- [Documentation](#-documentation)\n- [Contributing](#-contributing)\n- [License](#-license)\n- [Author](#-author)\n\n\u003c/details\u003e\n\n---\n\n## What's New in v5.0\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003ev5.0 — AI-first redesign (click to expand)\u003c/kbd\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\nv5.0 is an **AI-first redesign**. Every project surface is now machine-operable end-to-end so Claude Code can install, configure, snooze, troubleshoot, and upgrade the project on a human's behalf without any clicks, prompts, or doc reading.\n\n| Highlight | Effect |\n|---|---|\n| **`audio-hooks` JSON CLI** | Single binary with 27 subcommands. JSON to stdout, stable error codes + suggested commands. |\n| **`/audio-hooks` SKILL** | Natural-language activation: \"snooze audio for an hour\" — Claude runs it for you. |\n| **NDJSON structured logging** | Schema `audio-hooks.v1` with stable error code enums. |\n| **Plugin-native install** | Two commands and you're done. |\n| **4 new hook events** | `PermissionDenied`, `CwdChanged`, `FileChanged`, `TaskCreated` — 26 total. |\n| **Native matcher routing** | `hooks.json` registers per-matcher handlers with unique audio per variant. |\n| **Rate-limit alerts** | One-shot warning at 80%/95% of your 5h or 7d quota. |\n| **TTS speak Claude's reply** | Instead of \"Task completed\", TTS speaks Claude's actual final message. |\n| **Status line with context monitor** | Color-coded Context and API Quota bars with `/compact` reminders. |\n| **ElevenLabs audio generator** | One-line manifest edit + one-command rebuild for new audio. |\n\n### v5.0 in Action\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd width=\"50%\" align=\"center\"\u003e\n        \u003cimg src=\"docs/images/plugin-installed.png\" alt=\"Plugin Installed\" width=\"100%\"/\u003e\n        \u003cbr/\u003e\u003cem\u003ePlugin Installed — 26 hooks registered\u003c/em\u003e\n      \u003c/td\u003e\n      \u003ctd width=\"50%\" align=\"center\"\u003e\n        \u003cimg src=\"docs/images/skill-registration.png\" alt=\"SKILL Registration\" width=\"100%\"/\u003e\n        \u003cbr/\u003e\u003cem\u003e/audio-hooks SKILL active\u003c/em\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd width=\"50%\" align=\"center\"\u003e\n        \u003cimg src=\"docs/images/statusline-context-monitor.png\" alt=\"Status Line\" width=\"100%\"/\u003e\n        \u003cbr/\u003e\u003cem\u003eContext monitor status line\u003c/em\u003e\n      \u003c/td\u003e\n      \u003ctd width=\"50%\" align=\"center\"\u003e\n        \u003cimg src=\"docs/images/plugin-marketplace-detail.png\" alt=\"Marketplace\" width=\"100%\"/\u003e\n        \u003cbr/\u003e\u003cem\u003eMarketplace registration\u003c/em\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for full details.\n\n\u003c/details\u003e\n\n---\n\n## Install in 60 Seconds\n\n**For 99% of operations, you just talk to Claude Code in plain English.** The exception is the one-time install: `/reload-plugins` has no CLI equivalent, so the human types it exactly once. Everything else — configure, snooze, theme, webhook, troubleshoot, uninstall — is pure natural language.\n\n### Step 1 — Open Claude Code\n\n```bash\nclaude\n```\n\n### Step 2 — Install with one prompt\n\nPaste this into Claude Code:\n\n\u003e **Please install the audio-hooks plugin from `github.com/ChanMeng666/claude-code-audio-hooks`. Use the Bash tool to run `claude plugin marketplace add ChanMeng666/claude-code-audio-hooks` then `claude plugin install audio-hooks@chanmeng-audio-hooks`. After both commands complete, tell me to type `/reload-plugins` to activate the plugin.**\n\n### Step 3 — Type `/reload-plugins` (the one manual slash command)\n\n```text\n/reload-plugins\n```\n\n### Step 4 — Verify and configure with one prompt\n\n\u003e **Verify audio-hooks works by running `audio-hooks diagnose` and `audio-hooks test all`. Then switch to the chime audio theme.**\n\n**Total:** 1 shell command + 2 natural-language prompts + 1 slash command = **4 things**. From here on: natural language forever.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003eInstall flow diagram\u003c/kbd\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n```mermaid\nsequenceDiagram\n    participant Human\n    participant Terminal\n    participant Claude as Claude Code\n    participant Bash as Bash tool\n    participant Skill as /audio-hooks SKILL\n    participant CLI as audio-hooks CLI\n\n    Human-\u003e\u003eTerminal: type `claude` to start a session\n    Human-\u003e\u003eClaude: \"install audio-hooks plugin from\u003cbr/\u003egithub.com/ChanMeng666/claude-code-audio-hooks via\u003cbr/\u003e`claude plugin marketplace add` and `claude plugin install`\"\n    Claude-\u003e\u003eBash: claude plugin marketplace add ChanMeng666/claude-code-audio-hooks\n    Bash--\u003e\u003eClaude: \"Successfully added marketplace\"\n    Claude-\u003e\u003eBash: claude plugin install audio-hooks@chanmeng-audio-hooks\n    Bash--\u003e\u003eClaude: \"Installed audio-hooks. Run /reload-plugins to apply.\"\n    Claude--\u003e\u003eHuman: \"Plugin installed.\u003cbr/\u003eType /reload-plugins to activate it.\"\n\n    rect rgb(255, 230, 200)\n        Note over Human: The one manual slash command in the whole flow\n        Human-\u003e\u003eClaude: /reload-plugins\n        Claude--\u003e\u003eHuman: \"Reloaded: 8 plugins, 37 hooks, 5 skills\"\n    end\n\n    Human-\u003e\u003eClaude: \"verify audio-hooks works and switch to chime audio\"\n    Claude-\u003e\u003eSkill: SKILL activates on intent\n    Claude-\u003e\u003eBash: audio-hooks diagnose\n    Bash--\u003e\u003eClaude: {\"ok\":true,\"errors\":[],\"warnings\":[]}\n    Claude-\u003e\u003eBash: audio-hooks test all\n    Bash--\u003e\u003eClaude: {\"ok\":true,\"passed\":6,\"failed\":0}\n    Claude-\u003e\u003eBash: audio-hooks theme set custom\n    Bash--\u003e\u003eClaude: {\"ok\":true,\"theme\":\"custom\"}\n    Claude--\u003e\u003eHuman: \"Done. 26 hooks active, all tests passed,\u003cbr/\u003eaudio theme set to chimes.\"\n\n    Note over Human,CLI: From here on: pure natural language forever.\n```\n\n\u003c/details\u003e\n\n---\n\n## Just Say It — Natural Language Control\n\nOnce installed, you operate the project the same way — just talk to Claude Code. Every configuration is a single message:\n\n```mermaid\nsequenceDiagram\n    actor You as You\n    participant CC as Claude Code\n\n    rect rgb(219, 234, 254)\n    Note over You,CC: Audio Theme\n    You-\u003e\u003eCC: Switch audio-hooks to the chime theme.\n    CC--\u003e\u003eYou: audio-hooks theme set custom — switched to chimes.\n    You-\u003e\u003eCC: Switch audio-hooks to the voice theme.\n    CC--\u003e\u003eYou: audio-hooks theme set default — switched to ElevenLabs Jessica.\n    end\n\n    rect rgb(220, 252, 231)\n    Note over You,CC: Snooze \u0026 Mute\n    You-\u003e\u003eCC: Snooze audio for 30 minutes.\n    CC--\u003e\u003eYou: audio-hooks snooze 30m — muted until 3:45 PM.\n    You-\u003e\u003eCC: Snooze audio for 8 hours.\n    CC--\u003e\u003eYou: audio-hooks snooze 8h — quiet for the rest of the day.\n    You-\u003e\u003eCC: Unmute audio.\n    CC--\u003e\u003eYou: audio-hooks snooze off — audio resumed.\n    You-\u003e\u003eCC: Is audio currently muted?\n    CC--\u003e\u003eYou: audio-hooks snooze status — not snoozed.\n    end\n\n    rect rgb(254, 243, 199)\n    Note over You,CC: Hook Selection \u0026 Notification Mode\n    You-\u003e\u003eCC: Configure audio-hooks to only fire on stop,\u003cbr/\u003enotification, and permission_request —\u003cbr/\u003edisable everything else.\n    CC--\u003e\u003eYou: audio-hooks hooks enable-only stop notification\u003cbr/\u003epermission_request — 3 hooks active, rest disabled.\n    You-\u003e\u003eCC: Enable session_start and session_end hooks\u003cbr/\u003eso I hear when sessions begin and end.\n    CC--\u003e\u003eYou: session_start and session_end enabled.\n    You-\u003e\u003eCC: Switch audio-hooks to audio-only mode,\u003cbr/\u003eno desktop popups.\n    CC--\u003e\u003eYou: Notification mode set to audio_only.\n    You-\u003e\u003eCC: Switch to notification-only mode —\u003cbr/\u003edesktop popups but no audio.\n    CC--\u003e\u003eYou: Notification mode set to notification_only.\n    You-\u003e\u003eCC: For the stop hook only, use desktop\u003cbr/\u003enotification without audio.\n    CC--\u003e\u003eYou: Per-hook override: stop → notification_only.\n    You-\u003e\u003eCC: Make notifications more detailed.\n    CC--\u003e\u003eYou: Detail level set to verbose.\n    end\n```\n\n```mermaid\nsequenceDiagram\n    actor You as You\n    participant CC as Claude Code\n\n    rect rgb(237, 233, 254)\n    Note over You,CC: Webhooks \u0026 Integrations\n    You-\u003e\u003eCC: Send audio-hooks alerts to my Slack webhook\u003cbr/\u003eat https://hooks.slack.com/services/... and test it.\n    CC--\u003e\u003eYou: Webhook set to slack format. Test delivered.\n    You-\u003e\u003eCC: Send alerts to my Discord webhook instead.\n    CC--\u003e\u003eYou: Webhook set to discord format. Test delivered.\n    You-\u003e\u003eCC: Send alerts to ntfy at\u003cbr/\u003ehttps://ntfy.sh/my-channel. Test it.\n    CC--\u003e\u003eYou: Webhook set to ntfy format. Test delivered.\n    You-\u003e\u003eCC: Only send stop and stop_failure events\u003cbr/\u003eto the webhook, nothing else.\n    CC--\u003e\u003eYou: Webhook hook_types set to [stop, stop_failure].\n    end\n\n    rect rgb(254, 226, 226)\n    Note over You,CC: TTS \u0026 Rate Limits\n    You-\u003e\u003eCC: Enable audio-hooks TTS and have it speak\u003cbr/\u003eClaude's actual final message instead of\u003cbr/\u003ea generic announcement.\n    CC--\u003e\u003eYou: TTS enabled with speak_assistant_message = true.\n    You-\u003e\u003eCC: Set the stop hook TTS message to\u003cbr/\u003e\"Build finished\" instead of the default.\n    CC--\u003e\u003eYou: Custom TTS message for stop set.\n    You-\u003e\u003eCC: Make sure audio-hooks rate-limit alerts are\u003cbr/\u003eenabled with 80% and 95% thresholds for both\u003cbr/\u003e5-hour and 7-day windows.\n    CC--\u003e\u003eYou: Rate-limit alerts on — 80%, 95% for both windows.\n    end\n\n    rect rgb(207, 250, 254)\n    Note over You,CC: Status Line \u0026 Context Monitor\n    You-\u003e\u003eCC: Install the audio-hooks status line\u003cbr/\u003ein my Claude Code settings.\n    CC--\u003e\u003eYou: audio-hooks statusline install — restart to see it.\n    You-\u003e\u003eCC: Configure the status line to only show\u003cbr/\u003econtext usage.\n    CC--\u003e\u003eYou: Visible segments set to [context].\n    You-\u003e\u003eCC: Show only context and API quota\u003cbr/\u003ein the status line.\n    CC--\u003e\u003eYou: Visible segments set to [context, api_quota].\n    You-\u003e\u003eCC: Reset the status line to show all segments.\n    CC--\u003e\u003eYou: Visible segments reset to all.\n    end\n\n    rect rgb(232, 245, 233)\n    Note over You,CC: Focus Flow\n    You-\u003e\u003eCC: Enable the audio-hooks focus flow\u003cbr/\u003ewith breathing exercises.\n    CC--\u003e\u003eYou: Focus flow enabled — 4-7-8 breathing.\n    You-\u003e\u003eCC: Switch focus flow to hydration reminders.\n    CC--\u003e\u003eYou: Focus flow mode set to hydration.\n    You-\u003e\u003eCC: Only show focus flow if Claude thinks\u003cbr/\u003efor more than 30 seconds.\n    CC--\u003e\u003eYou: min_thinking_seconds set to 30.\n    end\n\n    rect rgb(229, 231, 235)\n    Note over You,CC: Monitor, Debug \u0026 Uninstall\n    You-\u003e\u003eCC: Enable the audio-hooks file_changed hook and\u003cbr/\u003econfigure it to watch .env and .envrc.\n    CC--\u003e\u003eYou: file_changed enabled, watching [.env, .envrc].\n    You-\u003e\u003eCC: Test all my audio-hooks hooks and tell me\u003cbr/\u003eif any failed.\n    CC--\u003e\u003eYou: audio-hooks test all — 26/26 passed.\n    You-\u003e\u003eCC: What's the current state of audio-hooks?\n    CC--\u003e\u003eYou: audio-hooks status — theme: default,\u003cbr/\u003e18 hooks enabled, 0 errors.\n    You-\u003e\u003eCC: Show me the last 20 errors and clear the log.\n    CC--\u003e\u003eYou: 2 errors found (WEBHOOK_TIMEOUT). Log cleared.\n    You-\u003e\u003eCC: What version of audio-hooks am I running?\n    CC--\u003e\u003eYou: v5.1.3, plugin install.\n    You-\u003e\u003eCC: Please uninstall audio-hooks completely.\n    CC--\u003e\u003eYou: Plugin uninstalled. All hooks removed.\n    end\n```\n\nEach prompt is one message. Claude Code parses it, runs the right subcommand(s), and reports back. **You don't memorise anything.**\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003ePlain-text prompt reference — copy-friendly table\u003c/kbd\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n| Goal | Paste this into Claude Code |\n|---|---|\n| **Audio Theme** | |\n| Switch to chime sounds | *\"Switch audio-hooks to the chime theme.\"* |\n| Switch to voice sounds | *\"Switch audio-hooks to the voice theme.\"* |\n| **Snooze \u0026 Mute** | |\n| Mute for 30 minutes | *\"Snooze audio for 30 minutes.\"* |\n| Mute for the rest of the day | *\"Snooze audio for 8 hours.\"* |\n| Unmute | *\"Unmute audio.\"* |\n| Check mute status | *\"Is audio-hooks currently muted?\"* |\n| **Hook Selection** | |\n| Only keep critical alerts | *\"Only fire audio-hooks on stop, notification, and permission_request. Disable everything else.\"* |\n| Enable session start/end sounds | *\"Enable the session_start and session_end hooks.\"* |\n| Enable tool execution sounds | *\"Enable pretooluse and posttooluse audio.\"* |\n| **Notification Mode** | |\n| Audio only, no desktop popups | *\"Switch audio-hooks to audio-only mode.\"* |\n| Desktop popups only, no audio | *\"Switch audio-hooks to notification-only mode.\"* |\n| Per-hook override | *\"For the stop hook, use desktop notification without audio.\"* |\n| Make notifications verbose | *\"Make audio-hooks notifications more detailed.\"* |\n| Disable all notifications | *\"Disable all audio-hooks notifications entirely.\"* |\n| **Focus Flow** | |\n| Breathing exercises | *\"Enable the audio-hooks focus flow with breathing exercises.\"* |\n| Hydration reminders | *\"Switch audio-hooks focus flow to hydration reminders.\"* |\n| Custom URL during thinking | *\"Set audio-hooks focus flow to open `https://example.com` during thinking.\"* |\n| Longer thinking delay | *\"Only show focus flow if Claude thinks for more than 30 seconds.\"* |\n| **Webhooks** | |\n| Send alerts to Slack | *\"Send audio-hooks alerts to my Slack webhook at `https://hooks.slack.com/services/...` and test it.\"* |\n| Send alerts to Discord | *\"Send audio-hooks alerts to my Discord webhook at `https://discord.com/api/webhooks/...` and test it.\"* |\n| Send alerts to Teams | *\"Send audio-hooks alerts to my Teams webhook. Test it.\"* |\n| Send alerts to ntfy | *\"Send audio-hooks alerts to `https://ntfy.sh/my-topic` in ntfy format. Test it.\"* |\n| Only webhook certain events | *\"Only send stop and stop_failure events to the webhook.\"* |\n| Disable webhook | *\"Disable the audio-hooks webhook.\"* |\n| **TTS (Text-to-Speech)** | |\n| Speak Claude's reply out loud | *\"Enable audio-hooks TTS and speak Claude's actual final message.\"* |\n| Custom TTS message for a hook | *\"Set the audio-hooks stop TTS message to 'Build finished'.\"* |\n| Limit spoken message length | *\"Limit audio-hooks TTS to 300 characters.\"* |\n| **Rate-limit Alerts** | |\n| Enable with custom thresholds | *\"Enable audio-hooks rate-limit alerts at 80% and 95% for both windows.\"* |\n| Adjust 5-hour thresholds | *\"Set audio-hooks 5-hour rate-limit thresholds to 75% and 90%.\"* |\n| **Status Line** | |\n| Add a status bar | *\"Install the audio-hooks status line.\"* |\n| Status bar: context only | *\"Only show context usage in the audio-hooks status line.\"* |\n| Status bar: context + API quota | *\"Show context and API quota in the audio-hooks status line.\"* |\n| Status bar: show everything | *\"Reset the audio-hooks status line to show all segments.\"* |\n| Remove status bar | *\"Uninstall the audio-hooks status line.\"* |\n| **File Watching** | |\n| Watch .env for changes | *\"Enable the audio-hooks file_changed hook and watch `.env` and `.envrc`.\"* |\n| **Monitor \u0026 Debug** | |\n| Test all hooks | *\"Test all audio-hooks and tell me if any failed.\"* |\n| Show current state | *\"Show the current audio-hooks status — enabled hooks, theme, and recent errors.\"* |\n| Why no sound? | *\"Audio-hooks isn't playing sounds. Diagnose and fix it.\"* |\n| Show recent errors | *\"Show me the last 20 audio-hooks errors.\"* |\n| Clear the log | *\"Clear the audio-hooks event log.\"* |\n| Check version | *\"What version of audio-hooks am I running?\"* |\n| Adjust debounce timing | *\"Set audio-hooks debounce to 1000ms.\"* |\n| **Uninstall** | |\n| Uninstall | *\"Please uninstall audio-hooks completely.\"* |\n\n\u003c/details\u003e\n\n---\n\n## How It Works\n\n```mermaid\nflowchart LR\n    CC[Claude Code event] --\u003e|stdin JSON| MR{native matcher\u003cbr/\u003erouting}\n    MR --\u003e|session_start_resume| HR[hook_runner.py]\n    MR --\u003e|stop_failure_rate_limit| HR\n    MR --\u003e|notification_idle_prompt| HR\n    MR --\u003e|...| HR\n\n    HR --\u003e|reads| RL[rate-limit pre-check\u003cbr/\u003emarker debounce]\n    HR --\u003e|reads| CFG[user_preferences.json]\n    HR --\u003e|reads| MARK[snooze + focus-flow markers]\n\n    HR --\u003e|fires| AUDIO[Audio playback\u003cbr/\u003e26 MP3s, 2 themes]\n    HR --\u003e|fires| NOTIF[Desktop notification]\n    HR --\u003e|fires| TTS[TTS announcement]\n    HR --\u003e|fires| WH[Webhook subprocess\u003cbr/\u003efire-and-forget]\n    HR --\u003e|writes| LOG[(NDJSON event log\u003cbr/\u003eschema audio-hooks.v1)]\n\n    style CC fill:#4A90E2,color:#fff\n    style HR fill:#7ED321,color:#000\n    style RL fill:#F5A623,color:#000\n    style AUDIO fill:#F5A623,color:#000\n    style WH fill:#9013FE,color:#fff\n    style LOG fill:#50E3C2,color:#000\n```\n\nClaude Code fires hook events as JSON on stdin. Native matchers in `hooks.json` route each event to `hook_runner.py` with a synthetic event name. The runner checks snooze state, rate-limit thresholds, debounce, and user filters — then fires audio playback, desktop notifications, TTS, and webhooks as configured.\n\n\u003ctable\u003e\u003ctbody\u003e\n\u003ctr\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd width=\"10000\"\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u0026nbsp;\u0026nbsp;\u003cstrong\u003eAI Control Surface\u003c/strong\u003e\u003c/summary\u003e\u003cbr\u003e\n\n```mermaid\nflowchart TB\n    USER[Human] --\u003e|natural language| CLAUDE[Claude Code]\n    CLAUDE --\u003e|activates| SKILL[/audio-hooks SKILL/]\n    SKILL --\u003e|invokes via Bash tool| BIN[bin/audio-hooks]\n\n    BIN --\u003e|reads| CONFIG[(user_preferences.json\u003cbr/\u003ein plugin data dir)]\n    BIN --\u003e|reads| MARKERS[(snooze + focus-flow markers)]\n    BIN --\u003e|reads| LOGS[(NDJSON event log)]\n    BIN --\u003e|writes| CONFIG\n    BIN --\u003e|writes| MARKERS\n\n    BIN --\u003e|invokes| HR[hook_runner.run_hook\u003cbr/\u003efor `audio-hooks test`]\n\n    BIN --\u003e|JSON to stdout| CLAUDE\n    CLAUDE --\u003e|reports back| USER\n\n    style USER fill:#4A90E2,color:#fff\n    style CLAUDE fill:#9013FE,color:#fff\n    style SKILL fill:#7ED321,color:#000\n    style BIN fill:#F5A623,color:#000\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd width=\"10000\"\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u0026nbsp;\u0026nbsp;\u003cstrong\u003eHook Lifecycle\u003c/strong\u003e\u003c/summary\u003e\u003cbr\u003e\n\n```mermaid\nflowchart TD\n    EVT[Hook event fires\u003cbr/\u003ee.g. Stop] --\u003e SNOOZE{snooze\u003cbr/\u003eactive?}\n    SNOOZE --\u003e|yes| EXIT0[exit 0 silent]\n    SNOOZE --\u003e|no| RL{rate_limits\u003cbr/\u003ein stdin?}\n    RL --\u003e|yes| RLCHK{crossed\u003cbr/\u003ethreshold?}\n    RLCHK --\u003e|yes| RLAUDIO[play warning audio\u003cbr/\u003e+ write debounce marker]\n    RLCHK --\u003e|no| DEB\n    RL --\u003e|no| DEB{debounced\u003cbr/\u003erecently?}\n    RLAUDIO --\u003e DEB\n    DEB --\u003e|yes| EXIT0\n    DEB --\u003e|no| FILTER{user filter\u003cbr/\u003ematches?}\n    FILTER --\u003e|yes, exclude| EXIT0\n    FILTER --\u003e|no| ENABLED{hook\u003cbr/\u003eenabled?}\n    ENABLED --\u003e|no| EXIT0\n    ENABLED --\u003e|yes| FIRE[play audio + notif + TTS + webhook]\n    FIRE --\u003e LOG[write NDJSON event]\n\n    style EVT fill:#4A90E2,color:#fff\n    style FIRE fill:#7ED321,color:#000\n    style RLAUDIO fill:#F5A623,color:#000\n    style EXIT0 fill:#999,color:#fff\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd width=\"10000\"\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u0026nbsp;\u0026nbsp;\u003cstrong\u003ePlugin Layout\u003c/strong\u003e\u003c/summary\u003e\u003cbr\u003e\n\n```mermaid\nflowchart TB\n    REPO[claude-code-audio-hooks/]\n\n    REPO --\u003e CP[.claude-plugin/marketplace.json]\n    REPO --\u003e PLUGINS[plugins/audio-hooks/]\n    REPO --\u003e CANON[CANONICAL SOURCE]\n\n    PLUGINS --\u003e P_MANIFEST[.claude-plugin/plugin.json]\n    PLUGINS --\u003e P_HOOKS[hooks/hooks.json\u003cbr/\u003ematcher-scoped]\n    PLUGINS --\u003e P_RUNNER[runner/run.py]\n    PLUGINS --\u003e P_SKILL[skills/audio-hooks/SKILL.md]\n    PLUGINS --\u003e P_BIN[bin/ — audio-hooks + statusline]\n    PLUGINS --\u003e P_AUDIO[audio/ — bundled MP3s]\n    PLUGINS --\u003e P_CONFIG[config/default_preferences.json]\n\n    CANON --\u003e C_HOOKS[hooks/hook_runner.py]\n    CANON --\u003e C_BIN[bin/audio-hooks + audio-hooks.py + .cmd]\n    CANON --\u003e C_AUDIO[audio/default + audio/custom]\n    CANON --\u003e C_CONFIG[config/]\n    CANON --\u003e C_SCRIPTS[scripts/ — install + build-plugin + uninstall]\n\n    C_HOOKS -.-\u003e|build-plugin.sh syncs| P_HOOKS\n    C_BIN -.-\u003e|build-plugin.sh syncs| P_BIN\n    C_AUDIO -.-\u003e|build-plugin.sh syncs| P_AUDIO\n\n    style REPO fill:#4A90E2,color:#fff\n    style PLUGINS fill:#7ED321,color:#000\n    style CANON fill:#F5A623,color:#000\n```\n\n\u003c/details\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/tbody\u003e\u003c/table\u003e\n\n---\n\n## Key Features\n\n### Status Line with Context Monitor\n\nReal-time context window and API quota bars — color-coded warnings before Claude enters the \"agent dumb zone\".\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/images/statusline-context-monitor.png\" alt=\"Status Line — context window monitor\" width=\"720\"\u003e\n\u003c/p\u003e\n\n```text\n[Opus] Audio Hooks v5.1.3 | 6/26 Sounds | Webhook: ntfy | Theme: Voice\n[MUTED 23m]  feat/audio-v5  API Quota: 78%  Context: 65% (130K/200K)  /compact\n```\n\n| Color | Range | Meaning | Action |\n|---|---|---|---|\n| Green | \u003c 50% | Safe — agent performs well | Keep working |\n| Yellow | 50-80% | Caution — entering the \"dumb zone\" | Type `/compact` or `/clear` |\n| Red | \u003e 80% | Danger — agent makes frequent errors | Type `/compact` immediately |\n\n**Absolute counts (v5.1.3+).** When Claude Code reports the context window size, the segment also shows current/max tokens, e.g. `Context: 83% (166K/200K)`. This makes the math obvious when you `/model`-switch between context-window variants — switching from Opus 4.7 (1M) to Sonnet 4.6 (200K) keeps your tokens identical but shrinks the denominator 5×, so a sudden jump from `17%` to `83%` is **expected**, not a bug. See `docs/TROUBLESHOOTING.md#context-97-or-any-sudden-jump-right-after-switching-models` for the full explanation.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003e10 customisable segments\u003c/kbd\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n| Segment | Shows |\n|---|---|\n| `model` | Model name (e.g. `[Opus]`) |\n| `version` | Audio Hooks version |\n| `sounds` | Enabled sound count |\n| `webhook` | Webhook status |\n| `theme` | Audio theme |\n| `snooze` | Mute countdown (when active) |\n| `focus` | Focus Flow mode (when active) |\n| `branch` | Git branch name |\n| `api_quota` | API usage quota bar |\n| `context` | Context window usage bar |\n\n\u003c/details\u003e\n\n### Audio Themes\n\n| Theme | Style | Source |\n|---|---|---|\n| `default` | ElevenLabs **Jessica** voice — short spoken phrases like *\"Task completed\"* | `audio/default/*.mp3` |\n| `custom` | Modern UI sound effects (chimes, beeps) | `audio/custom/chime-*.mp3` |\n\nSay *\"switch to chimes\"* or *\"switch to voice\"* — Claude Code handles the rest.\n\n### 26 Hook Events\n\n26 events covering the full Claude Code lifecycle — from session start to file changes, permission requests to rate-limit warnings. 6 are enabled by default; toggle any with natural language.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003eFull hook events table\u003c/kbd\u003e\u003c/summary\u003e\n\u003cbr\u003e\n\n| Hook | Default | Audio file | Native matchers |\n|---|:-:|---|---|\n| `notification` | on | notification-urgent.mp3 | `permission_prompt` / `idle_prompt` / `auth_success` / `elicitation_dialog` |\n| `stop` | on | task-complete.mp3 | |\n| `subagent_stop` | on | subagent-complete.mp3 | agent type |\n| `permission_request` | on | permission-request.mp3 | tool name |\n| `permission_denied` | on | permission-denied.mp3 | |\n| `task_created` | on | task-created.mp3 | |\n| `task_completed` | | team-task-done.mp3 | |\n| `session_start` | | session-start.mp3 | `startup` / `resume` / `clear` / `compact` |\n| `session_end` | | session-end.mp3 | `clear` / `resume` / `logout` / `prompt_input_exit` |\n| `pretooluse` | | task-starting.mp3 | tool name |\n| `posttooluse` | | task-progress.mp3 | tool name |\n| `posttoolusefailure` | | tool-failed.mp3 | tool name |\n| `userpromptsubmit` | | prompt-received.mp3 | |\n| `subagent_start` | | subagent-start.mp3 | agent type |\n| `precompact` / `postcompact` | | notification-info.mp3 / post-compact.mp3 | `manual` / `auto` |\n| `stop_failure` | | stop-failure.mp3 | `rate_limit` / `authentication_failed` / `billing_error` / `server_error` / `unknown` |\n| `teammate_idle` | | teammate-idle.mp3 | |\n| `config_change` | | config-change.mp3 | |\n| `instructions_loaded` | | instructions-loaded.mp3 | |\n| `worktree_create` / `worktree_remove` | | worktree-create.mp3 / worktree-remove.mp3 | |\n| `elicitation` / `elicitation_result` | | elicitation.mp3 / elicitation-result.mp3 | |\n| `cwd_changed` | | cwd-changed.mp3 | |\n| `file_changed` | | file-changed.mp3 | literal filenames |\n\n\u003c/details\u003e\n\n### Webhooks\n\nFan out hook events to Slack, Discord, Teams, ntfy, or any HTTP endpoint. Versioned `audio-hooks.webhook.v1` payload. Fire-and-forget via subprocess — never blocks the hook. Say *\"send alerts to my Slack\"* and Claude Code sets it up.\n\n### Rate-limit Alerts\n\nWatches every hook's stdin for `rate_limits` and plays a one-shot warning at configurable thresholds (default 80%/95%). Each `(window, threshold, resets_at)` fires exactly once — warned at 80%, again at 95%, never spammed.\n\n### TTS — Speak Claude's Reply\n\nInstead of a static \"Task completed\", TTS speaks Claude's actual final message (truncated to 200 chars). Off by default — privacy-conscious. Say *\"speak Claude's actual reply when done\"* to enable.\n\n### Focus Flow\n\nAnti-distraction micro-task during Claude's thinking time: guided breathing exercise, hydration reminder, custom URL, or shell command. Auto-closes when Claude finishes. Say *\"enable focus flow with breathing exercises\"*.\n\n---\n\n## Technical Reference\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003eCLI, configuration, environment variables, error codes, logging, manual install (click to expand)\u003c/kbd\u003e\u003c/summary\u003e\n\n### `audio-hooks` CLI\n\nSingle Python binary on PATH. JSON output, no prompts, no spinners.\n\n| Subcommand | Purpose |\n|---|---|\n| `audio-hooks manifest` | Canonical introspection — every subcommand, hook, config key, error code, env var |\n| `audio-hooks manifest --schema` | JSON Schema for `user_preferences.json` |\n| `audio-hooks status` | Full state snapshot |\n| `audio-hooks version` | Version + install mode detection |\n| `audio-hooks get \u003cdotted.key\u003e` | Read any config key |\n| `audio-hooks set \u003cdotted.key\u003e \u003cvalue\u003e` | Write any config key (auto-coerces) |\n| `audio-hooks hooks list` | All 26 hooks with current state |\n| `audio-hooks hooks enable/disable \u003cname\u003e` | Toggle a hook |\n| `audio-hooks hooks enable-only \u003ca\u003e \u003cb\u003e` | Exclusive enable |\n| `audio-hooks theme list/set \u003cname\u003e` | Audio theme |\n| `audio-hooks snooze [duration]/off/status` | Mute hooks (default 30m) |\n| `audio-hooks webhook/set/clear/test` | Webhook config + test |\n| `audio-hooks tts set ...` | TTS config |\n| `audio-hooks rate-limits set ...` | Rate-limit alert thresholds |\n| `audio-hooks test \u003chook\\|all\u003e` | Smoke-test hooks |\n| `audio-hooks diagnose` | System check |\n| `audio-hooks logs tail/clear` | NDJSON event log |\n| `audio-hooks install/uninstall` | Non-interactive install/uninstall |\n| `audio-hooks statusline show/install/uninstall` | Status line management |\n\n### Configuration Keys\n\n| Key | Type | Default | Effect |\n|---|---|---|---|\n| `audio_theme` | `default` \\| `custom` | `default` | Voice recordings vs chimes |\n| `enabled_hooks.\u003chook\u003e` | bool | varies | Per-hook toggle |\n| `playback_settings.debounce_ms` | int | 500 | Min ms between same hook firing |\n| `notification_settings.mode` | enum | `audio_and_notification` | `audio_only` / `notification_only` / `audio_and_notification` / `disabled` |\n| `notification_settings.detail_level` | enum | `standard` | `minimal` / `standard` / `verbose` |\n| `webhook_settings.enabled` | bool | `false` | Webhook fan-out |\n| `webhook_settings.url` | string | `\"\"` | Target URL |\n| `webhook_settings.format` | enum | `raw` | `slack` / `discord` / `teams` / `ntfy` / `raw` |\n| `webhook_settings.hook_types` | array | `[\"stop\",\"notification\",...]` | Which hooks fire the webhook |\n| `tts_settings.enabled` | bool | `false` | TTS announcements |\n| `tts_settings.speak_assistant_message` | bool | `false` | TTS Claude's actual reply on stop |\n| `tts_settings.assistant_message_max_chars` | int | 200 | Truncation cap |\n| `rate_limit_alerts.enabled` | bool | `true` | Watch stdin rate_limits |\n| `rate_limit_alerts.five_hour_thresholds` | int[] | `[80, 95]` | 5h window thresholds |\n| `rate_limit_alerts.seven_day_thresholds` | int[] | `[80, 95]` | 7d window thresholds |\n| `focus_flow.enabled` / `mode` / `min_thinking_seconds` / `breathing_pattern` | mixed | off / `breathing` / 15 / `4-7-8` | Anti-distraction micro-task |\n| `statusline_settings.visible_segments` | string[] | `[]` (all) | Status line segments to show |\n\n### Environment Variables\n\n| Variable | Purpose |\n|---|---|\n| `CLAUDE_PLUGIN_DATA` | Plugin install state directory (auto-set by Claude Code) |\n| `CLAUDE_PLUGIN_ROOT` | Plugin install root (auto-set) |\n| `CLAUDE_AUDIO_HOOKS_DATA` | Explicit override for state directory |\n| `CLAUDE_AUDIO_HOOKS_PROJECT` | Explicit override for project root |\n| `CLAUDE_HOOKS_DEBUG` | `1` to write debug-level events to NDJSON log |\n| `CLAUDE_NONINTERACTIVE` | `1` to force scripts into non-interactive mode |\n| `ELEVENLABS_API_KEY` | Used by `scripts/generate-audio.py` (never logged) |\n\n### Stable Error Codes\n\n| Code | When | Suggested fix |\n|---|---|---|\n| `AUDIO_FILE_MISSING` | Audio file doesn't exist | `audio-hooks diagnose` |\n| `AUDIO_PLAYER_NOT_FOUND` | No audio player binary | `audio-hooks diagnose` |\n| `AUDIO_PLAY_FAILED` | Player exited with error | `audio-hooks test` |\n| `INVALID_CONFIG` | `user_preferences.json` malformed | `audio-hooks manifest --schema` |\n| `CONFIG_READ_ERROR` | Can't read config | `audio-hooks status` |\n| `WEBHOOK_HTTP_ERROR` | Webhook returned non-2xx | `audio-hooks webhook test` |\n| `WEBHOOK_TIMEOUT` | Webhook timed out | `audio-hooks webhook test` |\n| `NOTIFICATION_FAILED` | Desktop notification failed | `audio-hooks diagnose` |\n| `TTS_FAILED` | TTS engine failed | `audio-hooks tts set --enabled false` |\n| `SETTINGS_DISABLE_ALL_HOOKS` | `disableAllHooks: true` in settings | `audio-hooks diagnose` |\n| `DUAL_INSTALL_DETECTED` | Both install methods active | `bash scripts/uninstall.sh --yes` |\n| `PROJECT_DIR_NOT_FOUND` | Can't locate project | `audio-hooks status` |\n| `UNKNOWN_HOOK_TYPE` | Unrecognised hook name | `audio-hooks hooks list` |\n| `INTERNAL_ERROR` | Unexpected error | `audio-hooks logs tail` |\n\n### NDJSON Event Log\n\nEvery event is one JSON object per line at `${CLAUDE_PLUGIN_DATA}/logs/events.ndjson`. Schema `audio-hooks.v1`.\n\n```json\n{\"ts\":\"2026-04-11T10:23:45.123Z\",\"schema\":\"audio-hooks.v1\",\"level\":\"info\",\"hook\":\"stop\",\"session_id\":\"abc\",\"action\":\"play_audio\",\"audio_file\":\"chime-task-complete.mp3\",\"duration_ms\":42}\n```\n\nLevels: `debug`, `info`, `warn`, `error`. Log rotation: 5 MB cap, 3 files kept.\n\n### Manual Install Reference\n\n**Plugin install** (two slash commands inside Claude Code):\n\n```text\n/plugin marketplace add ChanMeng666/claude-code-audio-hooks\n/plugin install audio-hooks@chanmeng-audio-hooks\n/reload-plugins\n```\n\n**Legacy script install** (pre-v5.0, still works):\n\n```bash\ngit clone https://github.com/ChanMeng666/claude-code-audio-hooks.git\ncd claude-code-audio-hooks\nbash scripts/install-complete.sh    # auto non-interactive on non-TTY\n```\n\nBoth paths share the same `hook_runner.py` and `audio-hooks` CLI. They are mutually exclusive — `audio-hooks diagnose` reports `DUAL_INSTALL_DETECTED` if both are active.\n\n### ElevenLabs Audio Generator\n\n`scripts/generate-audio.py` reads `config/audio_manifest.json` and regenerates audio via the ElevenLabs API:\n\n```bash\nELEVENLABS_API_KEY=sk_... python scripts/generate-audio.py           # generate missing\nELEVENLABS_API_KEY=sk_... python scripts/generate-audio.py --force   # regenerate all\npython scripts/generate-audio.py --dry-run                           # preview\n```\n\nTo add a new audio file: edit `config/audio_manifest.json`, run the generator, then `bash scripts/build-plugin.sh`.\n\n\u003c/details\u003e\n\n---\n\n## Platform Support\n\n| Platform | Audio player | Status |\n|---|---|---|\n| **Windows** (PowerShell / Git Bash / WSL2) | PowerShell MediaPlayer | Fully supported |\n| **macOS** | `afplay` | Fully supported |\n| **Linux** | `mpg123` / `ffplay` / `paplay` / `aplay` (auto-detected) | Fully supported |\n\nPython 3.6+ is the only runtime requirement.\n\n---\n\n## Troubleshooting\n\n\u003ctable\u003e\u003ctbody\u003e\n\u003ctr\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd width=\"10000\"\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u0026nbsp;\u0026nbsp;\u003cstrong\u003eNo sound at all\u003c/strong\u003e\u003c/summary\u003e\u003cbr\u003e\n\nRun `audio-hooks diagnose`, look for any error code, and run its `suggested_command`. Or just say: *\"Audio-hooks isn't playing sounds. Diagnose and fix it.\"*\n\n\u003c/details\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd width=\"10000\"\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u0026nbsp;\u0026nbsp;\u003cstrong\u003eHearing double sounds\u003c/strong\u003e\u003c/summary\u003e\u003cbr\u003e\n\nBoth legacy script install and plugin install are active. Diagnose reports `DUAL_INSTALL_DETECTED`. Fix: `bash scripts/uninstall.sh --yes` (removes legacy, preserves config).\n\n\u003c/details\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd width=\"10000\"\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u0026nbsp;\u0026nbsp;\u003cstrong\u003ePlugin won't install\u003c/strong\u003e\u003c/summary\u003e\u003cbr\u003e\n\nRun `claude plugin validate plugins/audio-hooks` from the project root — surfaces manifest schema errors. v5.0.1+ verified clean on Claude Code v2.1.101.\n\n\u003c/details\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd width=\"10000\"\u003e\n\u003cdetails\u003e\n\u003csummary\u003e\u0026nbsp;\u0026nbsp;\u003cstrong\u003epretooluse / posttooluse too noisy\u003c/strong\u003e\u003c/summary\u003e\u003cbr\u003e\n\nThey fire on every tool execution (Read, Glob, Grep, etc.) — disabled by default for this reason. Enable explicitly with *\"enable pretooluse and posttooluse audio\"*.\n\n\u003c/details\u003e\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/tbody\u003e\u003c/table\u003e\n\n---\n\n## Uninstall\n\n**Plugin install:** say *\"uninstall audio-hooks\"* or manually:\n\n```text\n/plugin uninstall audio-hooks@chanmeng-audio-hooks\n```\n\n**Legacy script install:**\n\n```bash\nbash scripts/uninstall.sh --yes              # preserve config + audio\nbash scripts/uninstall.sh --yes --purge      # remove everything\n```\n\n---\n\n## For Developers\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ckbd\u003eRepository layout, workflow, and contribution guide (click to expand)\u003c/kbd\u003e\u003c/summary\u003e\n\n### Repository Layout\n\n```\nclaude-code-audio-hooks/\n├── .claude-plugin/marketplace.json\n├── plugins/audio-hooks/              # plugin layout (populated by build-plugin.sh)\n│   ├── .claude-plugin/plugin.json\n│   ├── hooks/hooks.json\n│   ├── runner/run.py\n│   ├── skills/audio-hooks/SKILL.md\n│   ├── bin/\n│   ├── audio/\n│   └── config/default_preferences.json\n├── hooks/hook_runner.py              # CANONICAL\n├── bin/                              # CANONICAL\n│   ├── audio-hooks / audio-hooks.py / audio-hooks.cmd\n│   └── audio-hooks-statusline / .py / .cmd\n├── audio/                            # CANONICAL: 26 default + 26 custom\n├── config/\n│   ├── default_preferences.json\n│   ├── user_preferences.schema.json\n│   └── audio_manifest.json\n├── scripts/\n│   ├── install-complete.sh / install-windows.ps1\n│   ├── uninstall.sh / build-plugin.sh\n│   ├── generate-audio.py\n│   └── ...\n├── CLAUDE.md\n├── README.md\n└── CHANGELOG.md\n```\n\n### Workflow\n\n1. Edit canonical files (`/hooks/`, `/bin/`, `/audio/`, `/config/`)\n2. Run `bash scripts/build-plugin.sh` to sync into plugin layout\n3. CI verifies in-sync via `bash scripts/build-plugin.sh --check`\n4. Validate: `claude plugin validate plugins/audio-hooks`\n5. Test: `python bin/audio-hooks.py test all`\n\n### Contributing\n\nPull requests welcome. Fork, clone, make changes to canonical files, run `build-plugin.sh`, validate, test end-to-end, and submit with a conventional commit message.\n\n\u003c/details\u003e\n\n---\n\n## Documentation\n\n| Document | Purpose |\n|---|---|\n| [**CLAUDE.md**](CLAUDE.md) | Canonical AI-facing operating guide |\n| [**CHANGELOG.md**](CHANGELOG.md) | Detailed version history |\n| [**docs/ARCHITECTURE.md**](docs/ARCHITECTURE.md) | System architecture details |\n| `audio-hooks manifest` | Live source of truth — always up to date |\n\n---\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Design Philosophy** — This project is **AI-operated**, not AI-assisted. A typical CLI tool: the human learns the tool. **claude-code-audio-hooks**: the human says what they want, Claude Code learns the tool and does the work. The human is **upstream** of Claude Code, not downstream of the CLI.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## License\n\nThis project is licensed under the **MIT License** — see [LICENSE](LICENSE) for details.\n\n- Commercial use allowed\n- Modification allowed\n- Distribution allowed\n- Private use allowed\n\n---\n\n## Author\n\n\u003cdiv align=\"center\"\u003e\n  \u003ctable\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/ChanMeng666\"\u003e\n          \u003cimg src=\"https://github.com/ChanMeng666.png?size=100\" width=\"100px;\" alt=\"Chan Meng\"/\u003e\n          \u003cbr /\u003e\n          \u003csub\u003e\u003cb\u003eChan Meng\u003c/b\u003e\u003c/sub\u003e\n        \u003c/a\u003e\n        \u003cbr /\u003e\n        \u003csmall\u003eCreator \u0026 Lead Developer\u003c/small\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/table\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/ChanMeng666\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/GitHub-ChanMeng666-181717?style=flat\u0026logo=github\u0026logoColor=white\" alt=\"GitHub\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.linkedin.com/in/chanmeng666/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/LinkedIn-chanmeng666-0A66C2?style=flat\u0026logo=linkedin\u0026logoColor=white\" alt=\"LinkedIn\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://chanmeng.org/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Website-chanmeng.org-4285F4?style=flat\u0026logo=googlechrome\u0026logoColor=white\" alt=\"Website\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://buymeacoffee.com/chanmeng66u\" target=\"_blank\"\u003e\n    \u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" height=\"50\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003cdiv align=\"right\"\u003e\n\n[![][back-to-top]](#readme-top)\n\n\u003c/div\u003e\n\n\u003c!-- LINK DEFINITIONS --\u003e\n\n[back-to-top]: https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square\n\n[share-x-shield]: https://img.shields.io/badge/-Share%20on%20X-black?labelColor=black\u0026logo=x\u0026logoColor=white\u0026style=flat-square\n[share-x-link]: https://x.com/intent/tweet?text=Check%20out%20Claude%20Code%20Audio%20Hooks%20-%20AI-operated%20audio%20notifications%20for%20Claude%20Code\u0026url=https%3A%2F%2Fgithub.com%2FChanMeng666%2Fclaude-code-audio-hooks\n\n[share-linkedin-shield]: https://img.shields.io/badge/-Share%20on%20LinkedIn-blue?labelColor=blue\u0026logo=linkedin\u0026logoColor=white\u0026style=flat-square\n[share-linkedin-link]: https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2FChanMeng666%2Fclaude-code-audio-hooks\n\n[share-reddit-shield]: https://img.shields.io/badge/-Share%20on%20Reddit-orange?labelColor=black\u0026logo=reddit\u0026logoColor=white\u0026style=flat-square\n[share-reddit-link]: https://www.reddit.com/submit?title=Claude%20Code%20Audio%20Hooks%20-%20AI-operated%20audio%20notifications\u0026url=https%3A%2F%2Fgithub.com%2FChanMeng666%2Fclaude-code-audio-hooks\n\n[share-telegram-shield]: https://img.shields.io/badge/-Share%20on%20Telegram-blue?labelColor=blue\u0026logo=telegram\u0026logoColor=white\u0026style=flat-square\n[share-telegram-link]: https://t.me/share/url?text=Claude%20Code%20Audio%20Hooks%20-%20AI-operated%20audio%20notifications\u0026url=https%3A%2F%2Fgithub.com%2FChanMeng666%2Fclaude-code-audio-hooks\n\n[share-whatsapp-shield]: https://img.shields.io/badge/-Share%20on%20WhatsApp-green?labelColor=green\u0026logo=whatsapp\u0026logoColor=white\u0026style=flat-square\n[share-whatsapp-link]: https://api.whatsapp.com/send?text=Check%20out%20Claude%20Code%20Audio%20Hooks%20-%20AI-operated%20audio%20notifications%20for%20Claude%20Code%20https%3A%2F%2Fgithub.com%2FChanMeng666%2Fclaude-code-audio-hooks\n","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"}