claude-code-sound-hooks 1.0.0

package/LICENSE

@@ -0,0 +1,36 @@
+MIT License
+
+Copyright (c) 2026 victorluu99
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+EXCEPTION — bundled audio files
+
+The MIT license above covers the source code only. It does NOT cover:
+
+  assets/sounds/goi-goi-may-xong-goi.mp3
+  assets/sounds/oi-ban-oi.mp3
+
+These are short Vietnamese meme clips. Copyright in them remains with their
+original creators; they are included here for personal, non-commercial use as
+notification sounds, and are not licensed for redistribution or commercial use.
+Replace them with your own audio via the --stop, --notification and
+--permission flags if you need a clean license.

package/README.md

@@ -0,0 +1,93 @@
+# claude-code-sound-hooks
+
+Nghe được tiếng khi Claude Code làm xong, khi nó xin quyền, và khi nó gọi bạn.
+Cài bằng một lệnh. macOS only.
+
+*Sound notifications for Claude Code. One command to install. macOS only.*
+
+```bash
+npx claude-code-sound-hooks install
+```
+
+Hoặc cài thẳng từ GitHub, không cần chờ npm:
+
+```bash
+npx github:VictorLuu99/claude-code-sound-hooks install
+```
+
+Mở session Claude Code mới là xong.
+
+## Nó cài gì
+
+| Hook event | Khi nào kêu | Sound |
+| --- | --- | --- |
+| `Stop` | Claude trả lời xong | `goi-goi-may-xong-goi.mp3` |
+| `PermissionRequest` | Claude xin quyền chạy gì đó | `oi-ban-oi.mp3` |
+| `Notification` | Claude cần bạn để ý | `/System/Library/Sounds/Glass.aiff` |
+
+Sound được copy vào `~/.claude/sounds/claude-code-sound-hooks/`, và ba hook được
+thêm vào `~/.claude/settings.json`.
+
+## Lệnh
+
+```bash
+npx claude-code-sound-hooks install      # cài
+npx claude-code-sound-hooks status       # xem đang cài gì
+npx claude-code-sound-hooks uninstall    # gỡ sạch
+```
+
+Muốn dùng sound của bạn:
+
+```bash
+npx claude-code-sound-hooks install \
+  --stop ~/Music/xong-roi.mp3 \
+  --notification /System/Library/Sounds/Ping.aiff \
+  --permission ~/Music/cho-em-hoi.mp3
+```
+
+`--config-dir <path>` để trỏ vào một thư mục config khác `~/.claude`.
+
+Bất kỳ format nào `afplay` chơi được đều dùng được: mp3, aiff, wav, m4a.
+
+## Hook của bạn có bị mất không
+
+Không. `install` chỉ *thêm* hook, mọi thứ khác trong `settings.json` giữ nguyên —
+kể cả hook bạn tự viết trên cùng event `Stop`. `uninstall` chỉ xoá đúng hook do
+package này tạo ra.
+
+Trước mỗi lần ghi, `settings.json` được backup thành
+`settings.json.backup-<timestamp>` ngay cạnh nó. Chạy `install` nhiều lần cũng
+chỉ có một hook mỗi event, không bị nhân đôi.
+
+Nếu `settings.json` đang lỗi JSON, `install` dừng lại và **không ghi gì** — bạn
+sửa file trước đã.
+
+## Yêu cầu
+
+macOS (dùng `afplay`, có sẵn trong macOS) và Node 18 trở lên.
+`package.json` khai báo `"os": ["darwin"]` nên npm sẽ từ chối cài trên
+Windows/Linux.
+
+## Dev
+
+```bash
+npm test    # 35 test, không cần dependency nào
+```
+
+Không có runtime dependency. Logic merge `settings.json` nằm trong
+[`src/settings.js`](src/settings.js) và thuần object-in / object-out, nên test
+được mà không chạm vào filesystem. [`src/fsops.js`](src/fsops.js) là module duy
+nhất có side effect.
+
+Thiết kế đầy đủ:
+[`docs/superpowers/specs/`](docs/superpowers/specs/2026-07-30-claude-code-sound-hooks-design.md).
+
+## License
+
+Code: MIT — xem [LICENSE](LICENSE).
+
+**Audio thì không.** Hai file `assets/sounds/goi-goi-may-xong-goi.mp3` và
+`assets/sounds/oi-ban-oi.mp3` là clip meme tiếng Việt ngắn, bản quyền thuộc về
+người tạo ra chúng, đi kèm đây chỉ để dùng cá nhân, phi thương mại. Chúng **không**
+nằm trong giấy phép MIT. Nếu bạn định dùng cho việc gì khác, thay bằng sound của
+bạn qua các flag `--stop` / `--notification` / `--permission` ở trên.

package/assets/play.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+# Plays one sound for a Claude Code hook.
+#
+# Every hook installed by claude-code-sound-hooks goes through this script, so
+# the path of its directory identifies our hooks when uninstalling. Keep it here.
+#
+# A missing sound exits 0 on purpose: a deleted mp3 should go quiet, not turn
+# every Claude Code stop into a failing hook.
+[ -n "$1" ] && [ -f "$1" ] || exit 0
+
+exec afplay "$1"

package/bin/cli.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import process from 'node:process';
+
+import { assertSupportedPlatform } from '../src/platform.js';
+import {
+  PACKAGE_NAME,
+  assetsDirFor,
+  packageAssetsDir,
+  resolveConfigDir,
+  settingsPathFor,
+} from '../src/paths.js';
+import { EVENTS, HOOK_TIMEOUT, buildCommands, soundFromCommand } from '../src/preset.js';
+import { applyPreset, findPreset, removePreset } from '../src/settings.js';
+import {
+  backupSettings,
+  installAssets,
+  readSettings,
+  removeAssets,
+  writeSettings,
+} from '../src/fsops.js';
+
+const USAGE = `Usage: npx ${PACKAGE_NAME} <command> [options]
+
+Commands:
+  install      Add the sound hooks to your Claude Code settings
+  uninstall    Remove them again and delete the copied sounds
+  status       Show which hooks are installed right now
+
+Options:
+  --stop <file>          Sound for the Stop hook (Claude finished)
+  --notification <file>  Sound for the Notification hook
+  --permission <file>    Sound for the PermissionRequest hook
+  --config-dir <path>    Claude config dir (default: $CLAUDE_CONFIG_DIR or ~/.claude)
+  -h, --help             Show this message`;
+
+const FLAG_TO_EVENT = {
+  '--stop': 'Stop',
+  '--notification': 'Notification',
+  '--permission': 'PermissionRequest',
+};
+
+class UsageError extends Error {}
+
+function parseArgs(argv) {
+  const overrides = {};
+  let configDir;
+  let command;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '-h' || arg === '--help') {
+      command = 'help';
+    } else if (arg === '--config-dir' || FLAG_TO_EVENT[arg]) {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('-')) {
+        throw new UsageError(`Option ${arg} needs a value.`);
+      }
+      if (arg === '--config-dir') configDir = value;
+      else overrides[FLAG_TO_EVENT[arg]] = value;
+      i += 1;
+    } else if (arg.startsWith('-')) {
+      throw new UsageError(`Unknown option: ${arg}`);
+    } else if (command === undefined) {
+      command = arg;
+    } else {
+      throw new UsageError(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  return { command: command ?? 'help', configDir, overrides };
+}
+
+function install({ configDir, overrides }) {
+  const assetsDir = assetsDirFor(configDir);
+  const settingsFile = settingsPathFor(configDir);
+
+  // Validate first: a typo in --stop must not leave assets copied or settings
+  // half-written.
+  for (const [event, file] of Object.entries(overrides)) {
+    if (!fs.existsSync(file)) {
+      throw new UsageError(`No such sound file for ${event}: ${file}`);
+    }
+  }
+  const { settings } = readSettings(settingsFile);
+
+  installAssets(packageAssetsDir(), assetsDir);
+  const commands = buildCommands(assetsDir, overrides);
+  const backup = backupSettings(settingsFile);
+  writeSettings(
+    settingsFile,
+    applyPreset(settings, { commands, marker: assetsDir, timeout: HOOK_TIMEOUT }),
+  );
+
+  console.log(`Installed ${PACKAGE_NAME}.`);
+  for (const event of EVENTS) {
+    console.log(`  ${event.padEnd(18)} ${soundFromCommand(commands[event])}`);
+  }
+  console.log(`\nSounds:   ${assetsDir}`);
+  console.log(`Settings: ${settingsFile}`);
+  if (backup) console.log(`Backup:   ${backup}`);
+  console.log('\nRestart Claude Code, or start a new session, to pick up the hooks.');
+}
+
+function uninstall({ configDir }) {
+  const assetsDir = assetsDirFor(configDir);
+  const settingsFile = settingsPathFor(configDir);
+
+  const { exists, settings } = readSettings(settingsFile);
+  const removedEvents = Object.keys(findPreset(settings, assetsDir));
+
+  if (exists) {
+    const backup = backupSettings(settingsFile);
+    writeSettings(settingsFile, removePreset(settings, assetsDir));
+    if (backup && removedEvents.length > 0) console.log(`Backup:   ${backup}`);
+  }
+  removeAssets(assetsDir);
+
+  if (removedEvents.length > 0) {
+    console.log(`Removed hooks: ${removedEvents.join(', ')}`);
+  } else {
+    console.log(`${PACKAGE_NAME} was not installed; nothing to remove.`);
+  }
+  console.log('Your other hooks were left alone.');
+}
+
+function status({ configDir }) {
+  const assetsDir = assetsDirFor(configDir);
+  const settingsFile = settingsPathFor(configDir);
+
+  const { settings } = readSettings(settingsFile);
+  const found = findPreset(settings, assetsDir);
+
+  console.log(`Settings: ${settingsFile}`);
+  console.log(`Sounds:   ${assetsDir}\n`);
+
+  if (Object.keys(found).length === 0) {
+    console.log(`${PACKAGE_NAME} is not installed. Run: npx ${PACKAGE_NAME} install`);
+    return;
+  }
+
+  for (const event of EVENTS) {
+    const commands = found[event];
+    if (!commands) {
+      console.log(`  ${event.padEnd(18)} -`);
+      continue;
+    }
+    for (const command of commands) {
+      const sound = soundFromCommand(command);
+      const missing = sound && !fs.existsSync(sound) ? '  (file missing!)' : '';
+      console.log(`  ${event.padEnd(18)} ${sound}${missing}`);
+    }
+  }
+}
+
+function main(argv) {
+  const { command, configDir, overrides } = parseArgs(argv);
+
+  if (command === 'help') {
+    console.log(USAGE);
+    return;
+  }
+
+  const commands = { install, uninstall, status };
+  const run = commands[command];
+  if (!run) throw new UsageError(`Unknown command: ${command}`);
+
+  assertSupportedPlatform(process.platform);
+  run({ configDir: resolveConfigDir(configDir), overrides });
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  if (error instanceof UsageError) {
+    console.error(`${error.message}\n\n${USAGE}`);
+  } else {
+    console.error(error.message);
+  }
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "claude-code-sound-hooks",
+  "version": "1.0.0",
+  "description": "One command to install sound notifications for Claude Code on macOS — hear when Claude finishes, needs permission, or notifies you.",
+  "type": "module",
+  "bin": {
+    "claude-code-sound-hooks": "bin/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hooks",
+    "sound",
+    "notification",
+    "afplay",
+    "macos"
+  ],
+  "author": "victorluu99",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VictorLuu99/claude-code-sound-hooks.git"
+  },
+  "bugs": {
+    "url": "https://github.com/VictorLuu99/claude-code-sound-hooks/issues"
+  },
+  "homepage": "https://github.com/VictorLuu99/claude-code-sound-hooks#readme"
+}

package/src/fsops.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { PLAYER_NAME } from './paths.js';
+
+const SOUND_EXTENSIONS = /\.(mp3|aiff?|wav|m4a)$/i;
+
+/** Thrown when `settings.json` exists but is not valid JSON. */
+export class SettingsParseError extends Error {}
+
+/**
+ * Reads and parses `settings.json`. A missing or empty file counts as `{}`;
+ * unparseable content throws, because the caller must not overwrite a file it
+ * cannot understand.
+ */
+export function readSettings(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return { exists: false, settings: {} };
+    throw error;
+  }
+
+  if (raw.trim() === '') return { exists: true, settings: {} };
+
+  try {
+    return { exists: true, settings: JSON.parse(raw) };
+  } catch (error) {
+    throw new SettingsParseError(`Could not parse ${file}: ${error.message}`);
+  }
+}
+
+/** Copies the current settings aside. Returns the backup path, or null. */
+export function backupSettings(file) {
+  if (!fs.existsSync(file)) return null;
+
+  const stamp = new Date().toISOString().replaceAll(':', '-');
+  const backup = `${file}.backup-${stamp}`;
+  fs.copyFileSync(file, backup);
+  return backup;
+}
+
+/** Writes via a temp file and rename, so an interrupted write cannot truncate. */
+export function writeSettings(file, settings) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  const temp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`);
+  fs.renameSync(temp, file);
+}
+
+/** Copies the bundled sounds and the wrapper script into the config dir. */
+export function installAssets(sourceDir, targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const soundsDir = path.join(sourceDir, 'sounds');
+  const sounds = fs.readdirSync(soundsDir).filter((name) => SOUND_EXTENSIONS.test(name));
+  for (const name of sounds) {
+    fs.copyFileSync(path.join(soundsDir, name), path.join(targetDir, name));
+  }
+
+  const player = path.join(targetDir, PLAYER_NAME);
+  fs.copyFileSync(path.join(sourceDir, PLAYER_NAME), player);
+  fs.chmodSync(player, 0o755);
+
+  return [...sounds, PLAYER_NAME];
+}
+
+export function removeAssets(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}

package/src/index.js

@@ -0,0 +1,19 @@
+export { assertSupportedPlatform } from './platform.js';
+export {
+  PACKAGE_NAME,
+  PLAYER_NAME,
+  assetsDirFor,
+  packageAssetsDir,
+  resolveConfigDir,
+  settingsPathFor,
+} from './paths.js';
+export {
+  DEFAULT_SOUNDS,
+  EVENTS,
+  HOOK_TIMEOUT,
+  buildCommands,
+  resolveSound,
+  shellQuote,
+  soundFromCommand,
+} from './preset.js';
+export { applyPreset, findPreset, removePreset } from './settings.js';

package/src/paths.js

@@ -0,0 +1,34 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const PACKAGE_NAME = 'claude-code-sound-hooks';
+export const PLAYER_NAME = 'play.sh';
+
+/** The `assets/` directory shipped inside this package. */
+export function packageAssetsDir() {
+  return fileURLToPath(new URL('../assets/', import.meta.url));
+}
+
+/**
+ * Where Claude Code keeps `settings.json`. `CLAUDE_CONFIG_DIR` wins over the
+ * default so people who relocate their config still get a working install.
+ */
+export function resolveConfigDir(override) {
+  if (override) return path.resolve(override);
+  if (process.env.CLAUDE_CONFIG_DIR) return path.resolve(process.env.CLAUDE_CONFIG_DIR);
+  return path.join(os.homedir(), '.claude');
+}
+
+/**
+ * Our own directory under the config dir. Its absolute path doubles as the
+ * marker that identifies the hooks we installed, so every hook command we write
+ * contains it.
+ */
+export function assetsDirFor(configDir) {
+  return path.join(configDir, 'sounds', PACKAGE_NAME);
+}
+
+export function settingsPathFor(configDir) {
+  return path.join(configDir, 'settings.json');
+}

package/src/platform.js

@@ -0,0 +1,11 @@
+/**
+ * These hooks play sound with `afplay`, which only ships with macOS. Fail loudly
+ * rather than writing hooks that can never make a sound.
+ */
+export function assertSupportedPlatform(platform) {
+  if (platform !== 'darwin') {
+    throw new Error(
+      `claude-code-sound-hooks only supports macOS (it plays sound with afplay), but this is "${platform}".`,
+    );
+  }
+}

package/src/preset.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+
+import { PLAYER_NAME } from './paths.js';
+
+/** The Claude Code hook events we attach a sound to. */
+export const EVENTS = ['Stop', 'Notification', 'PermissionRequest'];
+
+/** Seconds Claude Code waits for the hook before giving up on it. */
+export const HOOK_TIMEOUT = 10;
+
+/**
+ * `bundled` sounds ship in this package and get copied next to the wrapper.
+ * `path` sounds already exist on every Mac, so we point straight at them.
+ */
+export const DEFAULT_SOUNDS = {
+  Stop: { bundled: 'goi-goi-may-xong-goi.mp3' },
+  Notification: { path: '/System/Library/Sounds/Glass.aiff' },
+  PermissionRequest: { bundled: 'oi-ban-oi.mp3' },
+};
+
+/** Wraps a value so the shell sees it as one literal argument. */
+export function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}
+
+export function resolveSound(event, assetsDir, override) {
+  if (override) return path.resolve(override);
+  const sound = DEFAULT_SOUNDS[event];
+  return sound.bundled ? path.join(assetsDir, sound.bundled) : sound.path;
+}
+
+/**
+ * Builds the shell command for each event. Everything goes through the wrapper
+ * script in `assetsDir`, which is what makes an installed hook recognisable as
+ * ours later — see `assetsDirFor`.
+ */
+export function buildCommands(assetsDir, overrides = {}) {
+  const player = shellQuote(path.join(assetsDir, PLAYER_NAME));
+
+  const commands = {};
+  for (const event of EVENTS) {
+    commands[event] = `${player} ${shellQuote(resolveSound(event, assetsDir, overrides[event]))}`;
+  }
+  return commands;
+}
+
+/** Recovers the sound path from a command we wrote, for display purposes. */
+export function soundFromCommand(command) {
+  const match = /'((?:[^']|'\\'')*)'\s*$/.exec(command);
+  return match ? match[1].replaceAll(`'\\''`, "'") : null;
+}

package/src/settings.js

@@ -0,0 +1,90 @@
+/**
+ * Pure transformations of a parsed `settings.json`. Nothing here touches the
+ * filesystem, and nothing mutates its argument.
+ *
+ * A hook is "ours" when its command contains the marker — the absolute path of
+ * our assets directory. Everything else in the file is left exactly as found,
+ * because users keep their own hooks in there too.
+ */
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isOurs(hook, marker) {
+  return isPlainObject(hook) && typeof hook.command === 'string' && hook.command.includes(marker);
+}
+
+/**
+ * Adds one hook per event. Existing hooks of ours are removed first, so calling
+ * this repeatedly leaves a single hook per event instead of a growing pile.
+ */
+export function applyPreset(settings, { commands, marker, timeout }) {
+  const base = removePreset(settings, marker);
+  const hooks = { ...(isPlainObject(base.hooks) ? base.hooks : {}) };
+
+  for (const [event, command] of Object.entries(commands)) {
+    const groups = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+    const hook = { type: 'command', command };
+    if (timeout !== undefined) hook.timeout = timeout;
+    groups.push({ hooks: [hook] });
+    hooks[event] = groups;
+  }
+
+  return { ...base, hooks };
+}
+
+/** Removes every hook of ours, pruning containers that end up empty. */
+export function removePreset(settings, marker) {
+  const next = structuredClone(settings ?? {});
+  if (!isPlainObject(next.hooks)) return next;
+
+  const hooks = {};
+  for (const [event, groups] of Object.entries(next.hooks)) {
+    if (!Array.isArray(groups)) {
+      hooks[event] = groups;
+      continue;
+    }
+
+    const keptGroups = [];
+    for (const group of groups) {
+      const inner = isPlainObject(group) && Array.isArray(group.hooks) ? group.hooks : null;
+      if (!inner || inner.length === 0) {
+        keptGroups.push(group);
+        continue;
+      }
+
+      const kept = inner.filter((hook) => !isOurs(hook, marker));
+      if (kept.length === inner.length) keptGroups.push(group);
+      else if (kept.length > 0) keptGroups.push({ ...group, hooks: kept });
+      // A group that held nothing but our hooks disappears with them.
+    }
+
+    if (keptGroups.length > 0) hooks[event] = keptGroups;
+  }
+
+  if (Object.keys(hooks).length > 0) next.hooks = hooks;
+  else delete next.hooks;
+  return next;
+}
+
+/** Maps each event to the commands of ours currently installed on it. */
+export function findPreset(settings, marker) {
+  const hooks = isPlainObject(settings) && isPlainObject(settings.hooks) ? settings.hooks : {};
+
+  const found = {};
+  for (const [event, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+
+    const commands = [];
+    for (const group of groups) {
+      const inner = isPlainObject(group) && Array.isArray(group.hooks) ? group.hooks : [];
+      for (const hook of inner) {
+        if (isOurs(hook, marker)) commands.push(hook.command);
+      }
+    }
+
+    if (commands.length > 0) found[event] = commands;
+  }
+  return found;
+}