Skip to content

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

Latest
Latest

Choose a tag to compare

View all tags
@vanci444-hue vanci444-hue released this 05 May 15:10
v0.3.0
77867ca

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

Assets 6
Loading