v0.3.0 — Hooks call afplay directly. No more silence after restart.

Claude Sound v0.3.0

This is a major reliability rework. If you've ever lost sound after restarting the app or the Mac, this release fixes that for good.

What changed

v0.2.x routed sound through HTTP: hook fires → request to a local server → server runs afplay. That chain has two silent-failure windows:

• App restart: 2-5s while the server boots, hooks fired in that window get dropped
• Mac reboot: hooks fired before the server starts up are dropped the same way

v0.3.0 takes the server out of the hot path. Hooks now write afplay /path/to/sound.aiff directly into ~/.claude/settings.json (Claude Code's command hook type). When Claude Code fires a hook it just runs the shell command — afplay is a macOS built-in that's always available. No local server, no daemon, no race window.

The app's role narrows accordingly: from "runtime that serves hooks" to "config tool that writes hooks". Open it to pick sounds / volumes / toggle the master switch, then quit. Sound keeps working whether or not the app is running.

Upgrading from v0.2.x

Just install v0.3.0 the usual way. On first launch it automatically:

1. Uninstalls the old LaunchAgent (no longer needed)
2. Rewrites any http-mode hooks in your settings.json to command-mode

Your sound preferences carry over. Nothing for you to do.

Removed

• LaunchAgent (~/Library/LaunchAgents/com.evan.claude-sound.plist) — gone, app no longer needs a background daemon
• "Launch at login (background service)" tray menu — gone
• /tmp/claude-sound.log / .err.log — gone, no daemon means no daemon log
• The Clash Verge / system-proxy direct-rule requirement — gone, hooks no longer make HTTP requests

What stays

• Menu-bar icon, master toggle, config panel, system sounds, custom uploads, per-event volume — all the same
• Hono server still runs while the app is open, but only to power the config UI (preview, file uploads, sound listing)
• ~/.claude/settings.json and ~/.claude/sounds/ paths unchanged

Downloads

Mac	File
Apple Silicon (M1/M2/M3/M4)	Claude Sound-0.3.0-arm64.dmg
Intel	Claude Sound-0.3.0.dmg

First launch needs the Gatekeeper bypass (still unsigned):

xattr -dr com.apple.quarantine /Applications/Claude\ Sound.app
open /Applications/Claude\ Sound.app

Full changelog

• feat: command-mode hooks become the default and only supported mode
• feat: auto-migrate http-mode hooks to command-mode on first v0.3.0 launch
• feat: auto-uninstall legacy LaunchAgent on first v0.3.0 launch
• chore: remove launch-at-login tray menu item
• chore: hide the http/command mode toggle in the config panel
• docs: rewrite README and README.en.md for the new architecture
• chore: bump to v0.3.0

Why this took a release

The story: I shipped v0.2.0, used it for a week, and started losing sound after every app restart. Spent an evening tracing it — the http hook was firing inside Claude Code's 2-5s window when the server wasn't reachable, and Claude Code's HTTP-hook semantics don't retry. The fix wasn't to make the server come up faster; it was to take the server out of the loop entirely.

I wrote up the whole debugging journey here: 《为了不再切回去看 Claude 跑没跑完，我做了个 Claude 的声音提醒》 (Chinese).

— Evan

v0.2.0 — macOS Menu-Bar App

✨ 重磅升级：从命令行工具变成 macOS 菜单栏小工具

不再需要装 Node.js / 跑命令。双击 .dmg 拖到 Applications 即用。

下载

• Apple Silicon (M1/M2/M3/M4)：Claude Sound-0.2.0-arm64.dmg（下面 Assets 区直接下载）
• Intel Mac：Claude Sound-0.2.0.dmg

第一次打开（绕 Gatekeeper）

xattr -dr com.apple.quarantine /Applications/Claude\ Sound.app
open /Applications/Claude\ Sound.app

新功能

• 🍎 macOS 菜单栏小工具：不占 Dock，顶部一个图标，点开关声音 / 配置
• 🛡️ LaunchAgent 后台守护：关 App / 重启电脑 server 都活着
• 🚀 双端通杀：终端 claude 命令 + Claude 桌面客户端都触发
• 🔊 一键开关声音：点菜单栏 →「声音 ON / OFF」
• 📁 自定义声音上传 + 试听 + 每事件独立音量
• 🌗 中英双语 + 亮暗主题

Clash Verge 用户必读

桌面客户端 + 系统代理会撞 502 坑，README 给了 4 条 prepend-rules 解决方案。

已知限制

• macOS only（依赖 afplay）
• 未做苹果开发者签名 → 首次打开需要 xattr 解封一行