v5.1.2 — fix Windows audio truncation

Patch release. Fixes a long-standing Windows-only audio-playback bug where the default permission-request.mp3 (~3.4 s) and elicitation.mp3 (~3.1 s) were always cut off ~0.4 s before the end. Affects every user on the default (voice) theme on Windows or WSL. Custom chime theme was unaffected (all chime files < 3 s).

Upgrading

claude plugin update audio-hooks@chanmeng-audio-hooks
# then in the Claude Code REPL:
/reload-plugins

Verify with audio-hooks version (should report 5.1.2).

What changed

Fixed

• Windows audio playback truncated clips > 3 s (#14, #15). Every PowerShell playback snippet in hooks/hook_runner.py — three fallback methods in play_audio_windows and the WSL path in play_audio_wsl — used a fixed Start-Sleep -Seconds 3 before calling $player.Stop(); $player.Close(). The bundled permission-request.mp3 is 3 396 ms, so PowerShell tore the player down ~396 ms before the clip finished. Exactly the "~0.4 s consistently cut off" described in the bug report.

  Fix: poll the media player for the actual clip length and sleep for duration + 500 ms tail buffer before tearing down. PresentationCore MediaPlayer polls $player.NaturalDuration.HasTimeSpan with a 1.5 s ceiling (Open() is async), then uses TotalMilliseconds. WMPlayer.OCX polls $w.currentMedia.duration. If the player never reports a duration (corrupt file, etc.), fallback is Start-Sleep -Seconds 10 — generous enough for any plausible clip, still bounded.

  The Python subprocess.Popen layer was already fire-and-forget; the fix closes the gap that was inside the PowerShell command string. macOS afplay and Linux mpg123/ffplay/paplay/aplay are unaffected — those players block until playback completes by default.

Empirical validation

Measured on Windows 11 against audio/default/permission-request.mp3:

Metric	v5.1.1	v5.1.2
MediaPlayer.NaturalDuration reported by the player	3 396 ms	3 396 ms
PowerShell lifetime (time until $player.Stop())	~3 000 ms	~3 915 ms
Audio truncated	~396 ms	0 ms

Version alignment

Every version reference bumped to 5.1.2:

File	Value
hooks/hook_runner.py HOOK_RUNNER_VERSION	5.1.2
bin/audio-hooks.py PROJECT_VERSION	5.1.2
.claude-plugin/marketplace.json (metadata + plugin entry)	5.1.2
plugins/audio-hooks/.claude-plugin/plugin.json	5.1.2
config/default_preferences.json (_version + version)	5.1.2
CLAUDE.md header + Version-history row	5.1.2
README.md badge + sequence diagram + status-line example	5.1.2
docs/ARCHITECTURE.md status-line example	5.1.2
plugins/audio-hooks/skills/audio-hooks/SKILL.md status-line example	5.1.2

Credit

Bug reported in #14 by @Basdanucha — thanks for the precise analysis (file size, bitrate, the three exact line numbers, and three concrete fix options to choose between). Made the fix a ~20-minute job.

Full changelog: https://github.com/ChanMeng666/claude-code-audio-hooks/blob/master/CHANGELOG.md#512---2026-04-20

v5.1.1 — critical import crash fix + CI smoke tests

Critical patch release. Everyone on v5.0.3 or v5.1.0 must upgrade — those releases crashed at import time and every audio-hooks subcommand failed.

Upgrading

claude plugin update audio-hooks@chanmeng-audio-hooks
# then in the Claude Code REPL:
/reload-plugins

Verify with audio-hooks version (should report 5.1.1) and audio-hooks diagnose.

What changed

Fixed

• NameError: name 'Tuple' is not defined at hook_runner.py import time (#10, #11). The runner used Tuple in module-level annotations on SYNTHETIC_EVENT_MAP and _resolve_synthetic_event but never imported it from typing. With no from __future__ import annotations in the file, CPython evaluated the annotations at import time and every audio-hooks subcommand — diagnose, status, version, test, hook dispatch — crashed before it could do anything. One-line fix: add Tuple to the existing typing import.

Added

• CI import-smoke workflow (#12, .github/workflows/smoke.yml). Runs on every push to master and every PR across 9 jobs (Ubuntu / Windows / macOS × Python 3.9 / 3.12 / 3.13), plus a plugin-in-sync job. Exercises:

  • import hook_runner on both the canonical hooks/ and the synced plugins/audio-hooks/hooks/ copy
  • audio-hooks version / status / diagnose
  • audio-hooks test all — all 26 hooks dispatch
  • scripts/build-plugin.sh --check — canonical/plugin drift detection

  Designed to catch exactly the class of bug that shipped in v5.0.3 / v5.1.0.

Version alignment

Prior to v5.1.1, the v5.1.0 tag was cut from the "context window monitor" feature commit without bumping the in-tree version strings, so v5.1.0 shipped reporting itself as 5.0.3. v5.1.1 makes every version reference consistent:

File	Value
hooks/hook_runner.py HOOK_RUNNER_VERSION	5.1.1
bin/audio-hooks.py PROJECT_VERSION	5.1.1
.claude-plugin/marketplace.json (metadata + plugin entry)	5.1.1
plugins/audio-hooks/.claude-plugin/plugin.json	5.1.1
config/default_preferences.json (_version + version)	5.1.1
CLAUDE.md header, README.md badge, docs status line examples	5.1.1

Credit

Bug reported in #10 — thanks to the reporter for the precise repro (line numbers, root cause analysis, and verified one-line patch).

Full changelog: https://github.com/ChanMeng666/claude-code-audio-hooks/blob/master/CHANGELOG.md#511---2026-04-18

v5.1.0 — Context Window Monitor & Customisable Status Line

What's new

Context window monitor in the status line

The status line now tracks context window usage in real time with color-coded thresholds that warn you before entering the "agent dumb zone" — when context exceeds 60–70%, Claude starts ignoring instructions and making basic coding errors.

Color	Range	What it means	What to do
🟢 Green	< 50%	Safe — agent performs well	Nothing, keep working
🟡 Yellow	50–80%	Caution — entering the "dumb zone"	Type /compact or /clear
🔴 Red	> 80%	Danger — agent makes frequent errors	Type /compact immediately

[Opus] 🔊 Audio Hooks v5.1.0 | 6/26 Sounds | Webhook: off | Theme: Voice
🌿 main  ████░░░░ API Quota: 60%  █████░░░ Context: 65% ⚠️ /compact

10 customisable status line segments

Users can choose exactly which segments to show. Just tell Claude Code in natural language:

• "Only show context usage in the status line" → shows just the context bar
• "Show context and API quota" → shows two progress bars
• "Show everything" → resets to all 10 segments (default)

Available segments: model, version, sounds, webhook, theme, snooze, focus, branch, api_quota, context.

audio-hooks set statusline_settings.visible_segments '["context"]'
audio-hooks set statusline_settings.visible_segments '["context","api_quota"]'
audio-hooks set statusline_settings.visible_segments '[]'   # show all (default)

Human-readable display labels (global accessibility)

All status line labels redesigned so non-English-native, non-technical users can understand them at a glance:

Before	After
ctx: 65%	Context: 65%
5h: 60%	API Quota: 60%
24/26 hooks	24/26 Sounds
theme: custom	Theme: Chimes
theme: default	Theme: Voice
SNOOZED	MUTED

Old config segment names (ctx, hooks, rate_limit) are still accepted for backwards compatibility.

SKILL.md now covers all features

The /audio-hooks SKILL (the natural-language interface Claude Code uses) now documents every project capability. 8 previously missing sections added:

• Check project status — audio-hooks status / audio-hooks version
• Notification settings — audio-only, notification-only, per-hook overrides
• Playback settings — debounce configuration
• Focus Flow — breathing exercises, min thinking seconds
• Uninstall — plugin and script paths
• Generic get/set — read/write any config key
• Webhook view — audio-hooks webhook (view current config)
• Status line customisation — segment selection with examples

Install / upgrade

If you already have the plugin installed, Claude Code will pick up the new version automatically on next plugin update. For new installs:

Tell Claude Code: "Install the audio-hooks plugin from github.com/ChanMeng666/claude-code-audio-hooks"

Then type /reload-plugins once. That's it — natural language forever after.

Files changed

• bin/audio-hooks-statusline.py — context bar, segment filtering, human-readable labels, backwards-compat alias system
• bin/audio-hooks.py — cmd_status now emits statusline_settings
• config/default_preferences.json — new statusline_settings.visible_segments key
• plugins/audio-hooks/skills/audio-hooks/SKILL.md — full feature coverage, 8 new sections
• CLAUDE.md — updated config table and decision tree
• README.md — new status line section with mermaid diagram, segment table, examples
• docs/ARCHITECTURE.md — updated statusline documentation

Full Changelog: v5.0.3...v5.1.0

v5.0.3 — Documentation correction: /reload-plugins is the one manual slash command

⚠ This is a documentation-only patch. No code changes. v5.0.2's README and release notes overclaimed that "the AI inside Claude Code runs the entire install autonomously". The user immediately caught this during real testing: the AI cannot invoke /reload-plugins (or any other slash command) because slash commands are interactive REPL primitives with no CLI equivalent and no Skill tool exposure. The user has to type /reload-plugins themselves once after install. v5.0.3 fixes the docs to be honest about this.

If you installed v5.0.2 successfully, you don't need to do anything — the runtime code is unchanged. v5.0.3 only updates README, CLAUDE.md, CHANGELOG, and the plugin manifest version field.

---

The honest install flow (4 user actions)

1. Open Claude Code (1 shell command)
   → type `claude` in any terminal

2. Ask Claude Code to install (1 natural-language prompt)
   → "Install the audio-hooks plugin from ChanMeng666/claude-code-audio-hooks
      by running `claude plugin marketplace add ChanMeng666/claude-code-audio-hooks`
      then `claude plugin install audio-hooks@chanmeng-audio-hooks` via Bash.
      Tell me to type /reload-plugins when it's done."
   → Claude Code runs both Bash commands and reports back

3. Type /reload-plugins (1 manual slash command — THE ONLY ONE)
   → This activates the plugin's hooks. There is no CLI equivalent for this
     command — it's REPL-only — so you must type it yourself.

4. Ask Claude Code to verify and configure (1 natural-language prompt)
   → "Verify with `audio-hooks diagnose` and `audio-hooks test all`,
      then switch to the chime audio theme."
   → Claude Code runs all three commands via Bash and reports back

Steps 2 and 4 are pure natural language. Steps 1 and 3 are unavoidable because they're entry/reload primitives the AI literally has no tool to invoke.

After step 4, every subsequent operation is pure natural language forever. You never type another command. You say "snooze for an hour", "why is there no sound", "send notifications to my Slack", and Claude Code translates each request into the right audio-hooks subcommand.

---

What the AI actually can and cannot do (verified end-to-end on Claude Code v2.1.101)

✅ The AI inside Claude Code CAN run via the Bash tool

Operation	CLI command
Add a plugin marketplace	claude plugin marketplace add <source>
List configured marketplaces	claude plugin marketplace list
Remove a marketplace	claude plugin marketplace remove <name>
Update marketplace metadata	claude plugin marketplace update [name]
Install a plugin	claude plugin install <plugin>
Uninstall a plugin	claude plugin uninstall <plugin>
Enable/disable a plugin	claude plugin enable|disable <plugin>
Update a plugin	claude plugin update <plugin>
List installed plugins	claude plugin list
Validate a plugin manifest	claude plugin validate <path>
Every audio-hooks subcommand	audio-hooks status | diagnose | test | theme | snooze | webhook | tts | rate-limits | hooks list | set | get | logs | install | uninstall | statusline | version | manifest

❌ The AI CANNOT invoke (REPL-only, no tool exposure)

Slash command	Why it can't be automated
/reload-plugins	Interactive REPL command. Reads keystrokes from the human at the prompt. Has no CLI equivalent (verified via claude --help and claude plugin --help) and is not registered as a Skill.
/exit	Same.
/clear	Same.
/doctor	Same.
Any other built-in slash command	The Skill tool's documentation is explicit: "Do not use this tool for built-in CLI commands (like /help, /clear, etc.)". Built-in REPL commands are not skills and have no programmatic invocation path.

---

Why the previous overclaim happened

I assumed that because the SKILL system can invoke skill-defined commands (e.g. the plugin's own /audio-hooks SKILL), the same mechanism could invoke other slash commands like /reload-plugins. It cannot. The Skill tool only invokes user-defined skills, not built-in REPL commands.

The user's pushback caught the overclaim within hours of the v5.0.2 release. Lesson recorded: don't claim a workflow is fully automated until you've verified every step against a real install, not just a mental model. The AI control surface is still genuinely powerful for everything that has a CLI command, which is every other operation in this project — but /reload-plugins is the one gap that this release acknowledges in writing.

---

What changed in v5.0.3

Documentation only — no code changes. The runtime behavior is identical to v5.0.2.

• README.md (834 lines)

  • Tagline rewritten: "You type one slash command at install time. Then natural language forever."
  • "AI-first way" section restructured to 4 honest steps with the manual /reload-plugins step prominently labeled.
  • Mermaid sequence diagram updated: the manual /reload-plugins step is now highlighted in a contrasting color block.
  • "Why this matters" section adds an explicit honesty paragraph listing what the AI can and cannot run.
  • "Design philosophy" section's natural-language operating model paragraph rewritten: "the human types one slash command in their lifetime with this project."

• CLAUDE.md (323 lines)

  • "AI quickstart" rewritten as step-by-step instructions for Claude Code itself when operating the project on a human's behalf.
  • New "Critical" warning to Claude Code: "Do NOT pretend you can run /reload-plugins via the Bash tool — you cannot. Tell the user to type it, wait for them to confirm, then continue with verification."
  • Decision tree install row updated to: "Run claude plugin marketplace add and claude plugin install via the Bash tool. Then ask the user to type /reload-plugins (you cannot run this — REPL only)."

• CHANGELOG.md v5.0.3 entry with full lists of AI-can/AI-cannot, plus the explanation of why the overclaim happened.

• Version bumped 5.0.2 → 5.0.3 across hook_runner.py, bin/audio-hooks.py, marketplace.json, plugin.json, default_preferences.json, README.md, CLAUDE.md. The bump exists only so the manifest version reflects the doc fix.

---

Upgrading from v5.0.2

Inside Claude Code, ask:

Update audio-hooks to v5.0.3 by running claude plugin update audio-hooks@chanmeng-audio-hooks. Then tell me to type /reload-plugins.

Then type /reload-plugins. Done — same content as v5.0.2 plus the corrected docs.

If you installed via the legacy script install path, run:

git pull
bash scripts/install-complete.sh

The script auto-detects non-TTY and installs without prompts.

---

Documentation

• README.md — public introduction with the corrected AI-first install path
• CLAUDE.md — canonical AI-facing operating guide
• docs/ARCHITECTURE.md — developer-facing architecture deep dive
• CHANGELOG.md — full version history

Diff from v5.0.2: v5.0.2...v5.0.3 (docs only, no code changes)

Full v5.0 line diff: v4.7.2...v5.0.3

v5.0.2 — AI-first redesign + post-install bugfix patch

⚠ CORRECTION (see v5.0.3): the headline tagline below ("You never type a command") is wrong. The AI inside Claude Code cannot invoke /reload-plugins (or any other interactive REPL slash command) because slash commands have no CLI equivalent and no Skill tool exposure. The honest install flow is 4 user actions: 1 shell command + 1 natural-language prompt + 1 manual /reload-plugins + 1 natural-language prompt. Steps 2 and 4 are pure natural language; steps 1 and 3 are unavoidable. After install, every other operation IS pure natural language forever — but the install itself is not 100% automated. v5.0.3 fixes the docs to be honest about this. The runtime code in v5.0.2 is unchanged and still correct — only the docs were wrong. Read the v5.0.3 release notes for the corrected install flow.

---

You never type a command. You never edit a config file. You never read a log.
You open Claude Code, say "install audio hooks", and Claude Code does everything else — install the plugin, register the 26 hook events, fetch the audio files, configure your preferences, and verify it works. From then on, you operate the project entirely through natural language: "snooze for an hour", "switch to chimes", "send notifications to my Slack", "why is there no sound". Claude Code translates each request into the right audio-hooks subcommand and reports back. The human is the requester. Claude Code is the operator.

This release rolls v5.0.0 (the AI-first redesign), v5.0.1 (the ElevenLabs audio addition), and v5.0.2 (the post-install bugfix patch + README rewrite) into one shippable artifact. It is the first release of the v5.0 line that has been fully verified end-to-end on a real Claude Code v2.1.101 install.

---

🤖 Install in one sentence

Open Claude Code (claude in any terminal) and paste this into the prompt:

Please install the claude-code-audio-hooks plugin from github.com/ChanMeng666/claude-code-audio-hooks. Add the marketplace, install the plugin, run /reload-plugins to activate it, then run audio-hooks diagnose and audio-hooks test all to verify everything works. Tell me when it is ready.

That is it. You do not clone the repo. You do not run any bash command. You do not type any slash command. Claude Codes plugin system fetches everything from this GitHub repo, registers all 26 hook events, plays a smoke test of every audio file, and reports back in plain English when it is done.

Then operate the project the same way:

You say	What Claude Code runs
"snooze audio for an hour"	audio-hooks snooze 1h
"switch to chime audio"	audio-hooks theme set custom
"send alerts to my Slack at https://hooks.slack.com/..."	audio-hooks webhook set --url ... --format slack then webhook test
"speak Claudes actual reply when done"	audio-hooks tts set --enabled true --speak-assistant-message true
"why is there no sound"	audio-hooks diagnose then runs the suggested fix for each error

See the README "AI-first way" section for the full prompt catalogue.

---

What changed across the v5.0 line

v5.0.0 — AI-first redesign

The defining release. Re-frames every project surface around Claude Code as the operator, not a human user.

Added:

• bin/audio-hooks JSON CLI with 27 subcommands. Default invocation returns the canonical machine manifest. No prompts, no colors, no spinners — JSON to stdout, errors with stable codes + suggested commands. Subcommands: manifest, manifest --schema, status, version, get, set, hooks list/enable/disable/enable-only, theme list/set, snooze, webhook set/clear/test, tts set, rate-limits set, test, diagnose, logs tail/clear, install, uninstall, update, statusline show/install/uninstall.
• /audio-hooks SKILL for natural-language activation. Trigger phrases like "snooze audio", "why is there no sound", "send notifications to Slack" activate the SKILL, which loads a structured guide telling Claude Code exactly which subcommand to run.
• NDJSON structured logging at ${CLAUDE_PLUGIN_DATA}/logs/events.ndjson with stable audio-hooks.v1 schema. 16 stable error code enums, each with hint and suggested_command fields. Log rotation: 5 MB cap, 3 files kept. Legacy debug.log, errors.log, hook_triggers.log removed.
• Claude Code plugin packaging: .claude-plugin/marketplace.json, plugins/audio-hooks/ self-contained layout, matcher-scoped hooks/hooks.json, plugin SKILL, bin/ on PATH, bundled audio. Install via /plugin marketplace add ChanMeng666/claude-code-audio-hooks then /plugin install audio-hooks@chanmeng-audio-hooks.
• Four new hook events: PermissionDenied (auto mode classifier denials), CwdChanged (working directory changes), FileChanged (watched file changes — matcher takes literal filenames), TaskCreated (sibling of TaskCompleted). Hook count is now 26.
• Native matcher routing via synthetic event names. hooks/hooks.json registers per-matcher handlers like session_start_resume, stop_failure_rate_limit, notification_idle_prompt instead of one wildcard handler per event. Per-variant audio overrides. Faster, configurable per-matcher, and per-handler async: true means a slow rate-limit-failure path does not block the auth-failure path.
• New stdin field parsing: last_assistant_message (Stop, SubagentStop), worktree.{name,branch,path}, agent_id, agent_type, notification_type, source (SessionStart), error_type (StopFailure), trigger (PreCompact/PostCompact), load_reason (InstructionsLoaded), permission_suggestions (PermissionRequest). Universal context suffix [session: foo, worktree: bar, agent: baz] appended to every notification.
• TTS speak Claudes actual reply: audio-hooks tts set --speak-assistant-message true — instead of speaking "Task completed", TTS the truncated last_assistant_message from the stop hook. Off by default for privacy.
• Rate-limit pre-check: inspects every hooks stdin rate_limits.{five_hour,seven_day}.used_percentage and plays a one-shot warning audio at configurable thresholds (default [80, 95]). Marker-debounced per (window, threshold, resets_at) so each reset window can re-fire each threshold exactly once.
• Fire-and-forget webhook subprocess dispatch: spawns a tiny detached Python subprocess that does the urlopen and exits, so the parent hook process can exit immediately even on slow webhooks. Versioned audio-hooks.webhook.v1 payload surfaces every new stdin field as a top-level key.
• Status line script bin/audio-hooks-statusline with two-line layout (model + version + enabled-hook count + theme on line 1, conditional snooze indicator + focus-flow indicator + worktree branch + colored rate-limit progress bar on line 2). Auto-registered via audio-hooks statusline install with refreshInterval: 60.
• Non-interactive scripts: install-complete.sh, install-windows.ps1, uninstall.sh, quick-setup.sh all auto-engage non-interactive mode when stdin is not a TTY or CLAUDE_NONINTERACTIVE=1 is set. uninstall.sh defaults to preserve config and audio (less destructive); pass --purge to remove them. Human-only menu scripts (configure.sh, test-audio.sh) emit a structured INTERACTIVE_SCRIPT JSON pointer when invoked non-interactively, redirecting to the audio-hooks CLI.
• CLAUDE.md rewritten as the canonical AI doc with operating principles, three-command quickstart, full hook catalogue, decision tree, error code reference, env var reference.

v5.0.1 — ElevenLabs audio addition

Added:

• Eight dedicated audio files for the v5.0 hooks, generated via the ElevenLabs API:
  • audio/default/{permission-denied,cwd-changed,file-changed,task-created}.mp3 (Jessica voice TTS)
  • audio/custom/chime-{permission-denied,cwd-changed,file-changed,task-created}.mp3 (sound-generation API)
• scripts/generate-audio.py — non-interactive Python generator. Reads config/audio_manifest.json (the single source of truth for every audio files text prompt + voice + theme + sound-effect parameters) and regenerates any subset via the ElevenLabs API. Default behavior: skip files that already exist. Flags: --force, --only filename1,filename2, --dry-run. Reads ELEVENLABS_API_KEY from environment, never writes the key to disk. Output is NDJSON per file plus a final summary JSON. Stdlib-only, no third-party dependencies.
• config/audio_manifest.json — single source of truth for audio file generation prompts, voice IDs, sound-effect parameters, and the TTS model.
• CLAUDE_PLUGIN_OPTION_* env var overlay in both hook_runner.py and bin/audio-hooks. The plugin manifests userConfig declarations now flow from Claude Codes plugin install through to the runtime config without writing to user_preferences.json. Webhook auto-enables when a URL is supplied via the env var.

v5.0.2 — post-install bugfix patch + AI-first README rewrite

The first end-to-end install of v5.0.1 on a real Claude Code v2.1.101 session surfaced five real bugs that were invisible from outside an actual install. v5.0.2 fixes all of them and rewrites the public README + docs to lead with the projects defining selling point: users never type a command, they just talk to Claude Code in natural language.

Fixed:

• userConfig schema rejected by claude plugin validate (fefe2c9). The v5.0.1 manifest used description+sensitive fields per my earlier read of the docs; the validator actually requires type (one of string|number|boolean|directory|file) plus title. Without this fix the plugin failed t...

v4.7.2 - Performance Optimization: Faster Hook Execution

Performance Optimization

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

Changes

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

Performance Impact

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

Zero Functional Changes

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

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

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

Bug Fix

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

Root Cause

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

Fix

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

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

Affected Platforms

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

Upgrade

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

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

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

What's New

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

How It Works

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

Available Modes

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

Quick Start

Add to config/user_preferences.json:

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

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

Breathing Patterns

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

Design Details

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

Upgrade

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

Then restart Claude Code.

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

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

What's New

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

1. Async Hook Execution

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

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

2. Smart Matchers

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

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

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

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

3. Richer Notification Context

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

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

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

4. Webhook Integration

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

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

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

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

Upgrade

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

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

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

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

What's New

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

New Hook Events

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

New Audio Files (16 total)

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

Changes

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

Upgrade

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

Then restart Claude Code.

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