⭕ Claude Voice Notifier

发布信息(Release Notes)

• Published by: @barry.dong

• Release Version: 1.1.2

• Released Date: 2026-06-23

• Release History:

  1. v1.0.6: Published Windows 11 64bit Edition
  2. v1.0.12: Solved npm and EXE installation's compatible issue for hooks status display
  3. v1.1.0: Published Cross-Platform Edition (macOS is supported)
  4. v1.1.1: Added automatic PATH configuration for macOS
  5. v1.1.2: Unified Windows and MacOS version numbers

特别说明(Special Notes)

• For English, please refer to the section as below after the Chinese section.

介绍

Claude Voice Notifier 是一个跨平台桌面应用（Windows 系统托盘 / macOS 菜单栏），当 Claude Code 弹出确认对话框或会话完成时，播放提示音提醒用户，减少用户盯着屏幕查看 Claude Code 运行情况的时间，通过声音通知，可实时提醒用户确认问题，了解当前会话完成情况。

主要特色和功能：

• 🔔 当 Claude Code 弹出确认对话框或需要用户输入时，播放提示音提醒用户。
• 🔔 当 Claude Code 当前对话完成时，也会播放提示音。
• 🎵 提示音可以自定义，支持 .wav / .mp3 格式。同时，可配置声音文件、播放次数、播放间隔。
• ⚙️ 轻量级运行，无需额外运行时，安装简单。
• ✅ 推荐使用 VS Code + Claude Code 插件 + Claude Voice Notifier 托盘组合模式运行。
• 🖥️ 适用于 Windows 11 和 MacOS 系统。

功能

• 🔔 在 Claude Code 需要用户确认时、会话完成时播放提示音
• 🎵 支持多种声音文件（.wav / .mp3）
• 🖥️ 系统托盘/菜单栏应用，最小化运行
• ⚡ 事件驱动信号监听：FileSystemWatcher (Windows) / DispatchSource (macOS)，非轮询
• 🪝 通过 Claude Code Hooks 自动触发提示音
• 🎨 墨黑色/白色双主题托盘菜单

安装

一键安装（推荐）

npm install -g claude-voice-notifier

前置要求：

• Node.js >= 14.0.0

验证安装

claude-voice-notifier --status

更新到最新版本

claude-voice-notifier update

或者：

npm install -g claude-voice-notifier@latest

使用方法

快速开始

1. 安装后，可以：

   A. 命令行直接启动：

   claude-voice-notifier

   B. Windows：双击 bin\ClaudeVoiceNotifier.exe

   C. macOS（ARM64）：双击 bin/darwin-arm64/ClaudeVoiceNotifier.app macOS（Intel）：双击 bin/darwin-x64/ClaudeVoiceNotifier.app

   D. 命令行查询版本信息：

   claude-voice-notifier --version 或者 claude-voice-notifier -v

   启动成功：会弹出加载动画窗口（橙色圆环呼吸动画），8 秒后自动消失，菜单栏（右上角）出现橙色圆环图标。

2. 点击菜单栏图标可以：

   • 启动/停止监控
   • 分别配置"对话框提醒"和"当前会话完成提醒"
   • 分别测试声音、选择提示音、设置播放次数和播放间隔
   • 安装/卸载 Hooks
   • 切换主题（浅色/墨黑色）
   • 切换语言（中文/English）
   • 显示日志
   • 退出程序

首次使用：安装 Hooks

点击菜单栏图标 → Hooks 配置 → 安装 Hooks，然后重启 VSCode 或运行 /hooks 重新加载配置。

可用声音

声音文件位于用户数据目录的 media/ 目录。当前内置声音：

| 文件 | 描述 | | ------ | ------ | | asterisk.wav | 星号提示音（默认） | | notify.wav | 通知音 | | ding.wav | 叮声 | | exclamation.wav | 警告音 | | alert.wav | 提醒音 |

添加自定义声音

1. 将 .wav 或 .mp3 文件放入 media/ 目录
2. 重启托盘应用
3. 右键托盘图标 → 对话框提醒 / 当前会话完成提醒 → 声音选择 → 选择新声音

工作原理

Claude Code Hook 触发 (AskUserQuestion / PermissionRequest / PreToolUse)
    ↓
trigger-sound.js 写入信号到 attention.signal
    ↓
┌─  平台分派  ─────────────────────┐
│ Windows: C# FileSystemWatcher   │
│ macOS:   Swift DispatchSource   │
│          FileSystemObject       │
└─────────────────────────────────┘
    ↓
检测到信号变化（事件驱动，非轮询）
    ↓
播放"对话框提醒"配置的声音

Claude Code Stop Hook 触发
    ↓
trigger-sound.js 写入 session-complete 信号
    ↓
┌─  平台分派  ─────────────────────┐
│ Windows: C# FileSystemWatcher   │
│ macOS:   Swift DispatchSource   │
│          FileSystemObject       │
└─────────────────────────────────┘
    ↓
播放"当前会话完成提醒"配置的声音

信号文件位置: ~/.claude-voice-notifier/attention.signal

信号文件内容为 JSON，例如：{"type":"dialog","timestamp":...} 或 {"type":"session-complete","timestamp":...}。

跨平台工作原理

npm install -g claude-voice-notifier
        ↓
   postinstall (install.js)
        ↓
   检测操作系统
        ↓
┌─ Windows──────┐    ┌─ macOS ─────────────────┐
│ 下载 exe       │    │ 下载 .app.zip           │
│ 放入 bin/      │    │ 解压到 bin/darwin-arm64/   │
└───────────────┘    └─────────────────────────┘
        ↓
   安装完成

配置

编辑 config.ini 自定义配置：

[General]
DefaultSound=asterisk.wav
DialogSound=asterisk.wav
SessionCompleteSound=exclamation.wav

[Media]
MediaDir=.\media
Extensions=.wav,.mp3

[Monitor]
CooldownMs=2000
EnableLogMonitor=false
EnableProcessLog=false

[DialogPlayback]
DialogPlayCount=1
DialogPlayInterval=600

[SessionCompletePlayback]
SessionCompletePlayCount=1
SessionCompletePlayInterval=600

[Appearance]
MenuTheme=dark
Language=zh-CN

| 配置项 | 说明 | | -------- | ---- | | DefaultSound | 默认声音文件 | | DialogSound | 对话框提醒声音文件 | | SessionCompleteSound | 当前会话完成提醒声音文件 | | MediaDir | 声音文件目录 | | Extensions | 支持的声音文件扩展名 | | CooldownMs | 信号检测冷却时间 | | DialogPlayCount | 对话框提醒播放次数（1-6） | | DialogPlayInterval | 对话框提醒播放间隔（ms） | | SessionCompletePlayCount | 会话完成提醒播放次数（1-6） | | SessionCompletePlayInterval | 会话完成提醒播放间隔（ms） | | MenuTheme | 菜单主题：dark 或 light | | Language | 语言：zh-CN 或 en-US |

技术架构

Windows (C# WPF)

| 层级 | 组件 | 描述 | | ------ | ------ | ------ | | UI | TrayApplication / TrayMenuBuilder / DarkMenuRenderer | 系统托盘 + 预构建菜单 + 深色/浅色主题 | | 服务 | SignalMonitor / SoundPlaybackService / HooksService | FileSystemWatcher 事件驱动 + 后台播放 + JSON 操作 | | 配置 | ConfigService / IniFileHelper / LocalizationService | INI 读写 + 热重载 + 中英文切换 | | 启动 | SplashWindow / App.xaml.cs | WPF 毛玻璃加载动画 + 橙色圆环呼吸动画 |

macOS (Swift/SwiftUI)

| 层级 | 组件 | 描述 | | ------ | ------ | ------ | | UI | AppDelegate / MenuBuilder | NSStatusItem 菜单栏 + 程序化绘制橙色圆环图标 | | 服务 | SignalMonitor / SoundPlayer / HooksService | DispatchSource 文件监控 + AVAudioPlayer + JSON 操作 | | 配置 | ConfigService / IniParser / LocalizationService | INI 读写 + 热重载 + 中英文切换 | | 启动 | SplashWindowController / SplashView | SwiftUI 毛玻璃加载动画 + 橙色圆环呼吸动画 |

平台对比

| 特性 | Windows (C#) | macOS (Swift) | | ---- | ------------ | ------------- | | 框架 | WPF + WinForms | SwiftUI + AppKit | | 系统托盘 | NotifyIcon | NSStatusItem | | 文件监控 | FileSystemWatcher | DispatchSourceFileSystemObject | | 音频播放 | SoundPlayer (WAV) | AVAudioPlayer (WAV/MP3) | | 图标绘制 | System.Drawing 程序化绘制 | Core Graphics 程序化绘制 | | 配置格式 | INI | INI | | 启动动画 | 8s 呼吸圆环 + 橙色边框 | 8s 呼吸圆环 + 橙色边框 | | 主题 | 浅色 / 墨黑色 | 浅色 / 墨黑色 | | 语言 | 中文 / English | 中文 / English |

许可证

MIT

作者

CC & CB & Barry

联系作者

• 邮箱：[email protected]

What is Claude Voice Notifier?

Claude Voice Notifier is a cross-platform desktop application (Windows system tray / macOS menu bar) that plays alert sounds when Claude Code pops up a confirmation dialog or when a conversation completes, reducing the need to stare at the screen while waiting for Claude Code. Audio notifications provide real-time alerts so you can confirm issues and stay informed of session status.

Key features and highlights:

• 🔔 Plays an alert sound when Claude Code needs user input or confirmation.
• 🔔 Plays an alert sound when a Claude Code conversation completes.
• 🎵 Customizable sounds, supporting .wav / .mp3 formats. Sound files, play count, and play interval are all configurable.
• ⚙️ Lightweight, no extra runtime required, easy installation.
• ✅ Designed for use with VS Code + Claude Code extension + Claude Voice Notifier tray combination.
• 🖥️ Built for Windows 11 x64 and MacOS.

Features

• 🔔 Plays sounds when Claude Code needs user confirmation or session completes
• 🎵 Supports multiple sound files (.wav / .mp3)
• 🖥️ System tray / menu bar application, minimize to tray
• ⚡ Event-driven signal detection: FileSystemWatcher (Windows) / DispatchSource (macOS), non-polling
• 🪝 Auto-triggers via Claude Code Hooks
• 🎨 Dark / Light dual-theme tray menu

Installation

npm install -g claude-voice-notifier

Prerequisites: Node.js >= 14.0.0

Usage

Quick Start

1. After installation, you can:

   A. Launch from command line:

   claude-voice-notifier

   B. Windows: Double-click bin\ClaudeVoiceNotifier.exe

   C. macOS (ARM64): Double-click bin/darwin-arm64/ClaudeVoiceNotifier.app macOS (Intel): Double-click bin/darwin-x64/ClaudeVoiceNotifier.app

   D. Check version from command line:

   claude-voice-notifier --version  or  claude-voice-notifier -v

   On successful launch: a splash animation window (orange ring breathing animation) appears, auto-dismisses after 8 seconds, and an orange ring icon appears in the menu bar (top-right).

2. Click the menu bar icon to:

   • Start / Stop monitoring
   • Configure "Dialog Alert" and "Session Complete Alert" separately
   • Test sound, select alert sounds, set play count and play interval
   • Install / Uninstall Hooks
   • Show logs
   • Exit

First Use: Install Hooks

Click the menu bar icon → Hooks Config → Install Hooks, then restart VSCode or run /hooks to reload config.

Available Sounds

Sound files are in the user data directory's media/ directory. Built-in sounds:

| File | Description | | ------ | ------ | | asterisk.wav | Asterisk alert (default) | | notify.wav | Notification sound | | ding.wav | Ding sound | | exclamation.wav | Warning sound | | alert.wav | Alert sound |

Adding Custom Sounds

1. Place .wav or .mp3 files in the media/ directory
2. Restart the tray app
3. Right-click tray icon → Dialog Alert / Session Complete Alert → Sound Selection → Choose new sound

How It Works

Claude Code Hook triggered (AskUserQuestion / PermissionRequest / PreToolUse)
    ↓
trigger-sound.js writes signal to attention.signal
    ↓
┌─ Platform dispatch ────────────┐
│ Windows: C# FileSystemWatcher  │
│ macOS:   Swift DispatchSource  │
│          FileSystemObject      │
└────────────────────────────────┘
    ↓
Signal change detected (event-driven, non-polling)
    ↓
Plays sound configured for "Dialog Alert"

Claude Code Stop Hook triggered
    ↓
trigger-sound.js writes session-complete signal
    ↓
┌─ Platform dispatch ────────────┐
│ Windows: C# FileSystemWatcher  │
│ macOS:   Swift DispatchSource  │
│          FileSystemObject      │
└────────────────────────────────┘
    ↓
Plays sound configured for "Session Complete Alert"

Signal file location: ~/.claude-voice-notifier/attention.signal

Signal file content is JSON, e.g.: {"type":"dialog","timestamp":...} or {"type":"session-complete","timestamp":...}.

Cross-Platform Installation Process

npm install -g claude-voice-notifier
        ↓
   postinstall (install.js)
        ↓
   Detect operating system
        ↓
┌─ Windows ──────┐    ┌─ macOS ──────────────────┐
│ Download exe   │    │ Download .app.zip         │
│ Place in bin/  │    │ Extract to bin/darwin-arm64/ │
└────────────────┘    └──────────────────────────┘
        ↓
   Installation complete

Configuration

Edit config.ini to customize settings:

[General]
DefaultSound=asterisk.wav
DialogSound=asterisk.wav
SessionCompleteSound=exclamation.wav

[Media]
MediaDir=.\media
Extensions=.wav,.mp3

[Monitor]
CooldownMs=2000
EnableLogMonitor=false
EnableProcessLog=false

[DialogPlayback]
DialogPlayCount=1
DialogPlayInterval=600

[SessionCompletePlayback]
SessionCompletePlayCount=1
SessionCompletePlayInterval=600

[Appearance]
MenuTheme=dark
Language=zh-CN

| Setting | Description | | -------- | ---- | | DefaultSound | Default sound file | | DialogSound | Dialog alert sound file | | SessionCompleteSound | Session complete alert sound file | | MediaDir | Sound file directory | | Extensions | Supported sound extensions, comma-separated | | CooldownMs | Signal detection cooldown time | | DialogPlayCount | Dialog alert play count (1-6) | | DialogPlayInterval | Dialog alert play interval (ms) | | SessionCompletePlayCount | Session complete alert play count (1-6) | | SessionCompletePlayInterval | Session complete alert play interval (ms) | | MenuTheme | Menu theme: dark or light | | Language | Language: zh-CN or en-US |

Technical Architecture

• Windows (C# WPF)

| Layer | Component | Description | | ------ | ------ | ------ | | UI | TrayApplication / TrayMenuBuilder / DarkMenuRenderer | System tray + pre-built menu + dark/light theme | | Services | SignalMonitor / SoundPlaybackService / HooksService | FileSystemWatcher event-driven + background playback + JSON operations | | Config | ConfigService / IniFileHelper / LocalizationService | INI read/write + hot reload + CN/EN switching | | Startup | SplashWindow / App.xaml.cs | WPF glass-morphism splash animation + orange ring breathing animation |

• macOS (Swift/SwiftUI)

| Layer | Component | Description | | ------ | ------ | ------ | | UI | AppDelegate / MenuBuilder | NSStatusItem menu bar + programmatic orange ring icon | | Services | SignalMonitor / SoundPlayer / HooksService | DispatchSource file monitoring + AVAudioPlayer + JSON operations | | Config | ConfigService / IniParser / LocalizationService | INI read/write + hot reload + CN/EN switching | | Startup | SplashWindowController / SplashView | SwiftUI glass-morphism splash animation + orange ring breathing animation |

Platform Comparison

| Feature | Windows (C#) | macOS (Swift) | | ------- | ------------ | ------------- | | Framework | WPF + WinForms | SwiftUI + AppKit | | System Tray | NotifyIcon | NSStatusItem | | File Monitor | FileSystemWatcher | DispatchSourceFileSystemObject | | Audio Playback | SoundPlayer (WAV) | AVAudioPlayer (WAV/MP3) | | Icon Drawing | System.Drawing programmatic | Core Graphics programmatic | | Config Format | INI | INI | | Splash Animation | 8s breathing ring + orange border | 8s breathing ring + orange border | | Theme | Light / Ink Black | Light / Ink Black | | Language | Chinese / English | Chinese / English |

License

MIT

Author

CC & CB & Barry

Contact

• Email: [email protected]