claude-sound 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,69 @@
+# claude-sound
+
+macOS-only CLI that configures **Claude Code Hooks** to play **bundled sounds** using `afplay`.
+
+- Setup UI: `npx claude-sound@latest`
+- Hook runner: `npx --yes claude-sound@latest play --event <Event> --sound <SoundId> --managed-by claude-sound`
+
+## Install / run
+
+```bash
+npx claude-sound@latest
+```
+
+You’ll be prompted to choose where to write settings:
+
+- Project (shared): `.claude/settings.json`
+- Project (local): `.claude/settings.local.json`
+- Global: `~/.claude/settings.json`
+
+Then you can enable/disable events and choose a sound per event. Selecting a sound plays a quick preview.
+
+## Commands
+
+```bash
+claude-sound list-events
+claude-sound list-sounds
+claude-sound play --sound ring1
+```
+
+## What gets written
+
+For each configured event, `claude-sound` writes a Claude hook handler like:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --yes claude-sound@latest play --event SessionStart --sound ring1 --managed-by claude-sound",
+            "async": true,
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`claude-sound` only manages hook handlers whose `command` contains `--managed-by claude-sound`.
+
+## Uninstall / remove hooks
+
+Run the setup again and choose **Remove all claude-sound hooks**, then **Apply**.
+
+Or manually delete any hook handlers whose command contains:
+
+```
+--managed-by claude-sound
+```
+
+## Notes
+
+- macOS only (requires `afplay`).
+- Hooks run `npx` each time the event fires. It’s simple and works everywhere, but may be slower than a local install.

package/assets/sounds/manifest.json

@@ -0,0 +1,42 @@
+[
+  {
+    "id": "ring1",
+    "file": "assets/sounds/ring1.wav"
+  },
+  {
+    "id": "ring2",
+    "file": "assets/sounds/ring2.wav"
+  },
+  {
+    "id": "ring3",
+    "file": "assets/sounds/ring3.wav"
+  },
+  {
+    "id": "ring4",
+    "file": "assets/sounds/ring4.wav"
+  },
+  {
+    "id": "ring5",
+    "file": "assets/sounds/ring5.wav"
+  },
+  {
+    "id": "ring6",
+    "file": "assets/sounds/ring6.wav"
+  },
+  {
+    "id": "ring7",
+    "file": "assets/sounds/ring7.wav"
+  },
+  {
+    "id": "ring8",
+    "file": "assets/sounds/ring8.wav"
+  },
+  {
+    "id": "ring9",
+    "file": "assets/sounds/ring9.wav"
+  },
+  {
+    "id": "ring10",
+    "file": "assets/sounds/ring10.wav"
+  }
+]

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "claude-sound",
+  "version": "0.1.0",
+  "description": "Configure Claude Code hooks to play bundled sounds on macOS (afplay).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "type": "module",
+  "bin": {
+    "claude-sound": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "assets"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "generate:sounds": "node ./scripts/generate-sounds.mjs",
+    "prepack": "npm run generate:sounds"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+import { intro, outro, select, isCancel, cancel, note, spinner } from '@clack/prompts';
+import process from 'node:process';
+import fs from 'node:fs/promises';
+import { playSound } from './play.js';
+import { listSounds } from './sounds.js';
+import {
+  HOOK_EVENTS,
+  configPathForScope,
+  readJsonIfExists,
+  writeJson,
+  getExistingManagedMappings,
+  applyMappingsToSettings
+} from './hooks.js';
+
+function usage(exitCode = 0) {
+  process.stdout.write(`\
+claude-sound (macOS)\n\nUsage:\n  npx claude-sound@latest                Interactive hook sound setup\n  claude-sound                          Interactive hook sound setup\n\n  claude-sound play --sound <id>         Play a bundled sound (uses afplay)\n  claude-sound list-sounds              List bundled sound ids\n  claude-sound list-events              List Claude hook event names\n\nOptions:\n  -h, --help                             Show help\n\nExamples:\n  npx claude-sound@latest\n  npx claude-sound@latest play --sound ring1\n`);
+  process.exit(exitCode);
+}
+
+function parseArg(flag) {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1) return null;
+  return process.argv[idx + 1] ?? null;
+}
+
+async function cmdPlay() {
+  const soundId = parseArg('--sound');
+  if (!soundId) {
+    process.stderr.write('Missing --sound <id>\n');
+    process.exit(1);
+  }
+
+  try {
+    await playSound(soundId);
+  } catch (err) {
+    process.stderr.write(`Failed to play sound '${soundId}': ${err?.message || err}\n`);
+    process.exit(1);
+  }
+}
+
+async function cmdListSounds() {
+  const sounds = await listSounds();
+  for (const s of sounds) process.stdout.write(s + '\n');
+}
+
+async function cmdListEvents() {
+  for (const e of HOOK_EVENTS) process.stdout.write(e + '\n');
+}
+
+async function interactiveSetup() {
+  intro('claude-sound');
+
+  const scope = await select({
+    message: 'Where do you want to write Claude Code hook settings?',
+    options: [
+      { value: 'project', label: 'Project (shared): .claude/settings.json' },
+      { value: 'projectLocal', label: 'Project (local): .claude/settings.local.json (gitignored)' },
+      { value: 'global', label: 'Global: ~/.claude/settings.json' }
+    ]
+  });
+
+  if (isCancel(scope)) {
+    cancel('Cancelled');
+    process.exit(0);
+  }
+
+  const projectDir = process.cwd();
+  const settingsPath = configPathForScope(scope, projectDir);
+
+  const existingRes = await readJsonIfExists(settingsPath);
+  if (!existingRes.ok) {
+    cancel(`Could not read/parse JSON at ${settingsPath}`);
+    note(String(existingRes.error?.message || existingRes.error), 'Error');
+    process.exit(1);
+  }
+
+  let settings = existingRes.value;
+
+  // Load existing mappings we previously wrote.
+  /** @type {Record<string, string>} */
+  let mappings = getExistingManagedMappings(settings);
+
+  const sounds = await listSounds();
+
+  // main loop
+  while (true) {
+    const options = HOOK_EVENTS.map((eventName) => {
+      const soundId = mappings[eventName];
+      const enabled = Boolean(soundId);
+      return {
+        value: eventName,
+        label: `${enabled ? '[x]' : '[ ]'} ${eventName}${soundId ? `  →  ${soundId}` : ''}`
+      };
+    });
+
+    options.push({ value: '__apply__', label: 'Apply (write settings)' });
+    options.push({ value: '__remove_all__', label: 'Remove all claude-sound hooks' });
+    options.push({ value: '__exit__', label: 'Exit (no changes)' });
+
+    const choice = await select({
+      message: `Configure hook sounds (${settingsPath})`,
+      options
+    });
+
+    if (isCancel(choice) || choice === '__exit__') {
+      cancel('No changes written');
+      process.exit(0);
+    }
+
+    if (choice === '__remove_all__') {
+      mappings = {};
+      note('All claude-sound mappings cleared (not written yet). Choose Apply to save.', 'Cleared');
+      continue;
+    }
+
+    if (choice === '__apply__') {
+      const s = spinner();
+      s.start('Writing settings...');
+      settings = applyMappingsToSettings(settings, mappings);
+      await writeJson(settingsPath, settings);
+      s.stop('Done');
+      outro(`Saved hooks to ${settingsPath}`);
+      return;
+    }
+
+    const eventName = choice;
+
+    const action = await select({
+      message: `Event: ${eventName}`,
+      options: [
+        { value: 'enable', label: mappings[eventName] ? 'Change sound' : 'Enable & choose sound' },
+        { value: 'disable', label: 'Disable (remove mapping)' },
+        { value: 'back', label: 'Back' }
+      ]
+    });
+
+    if (isCancel(action) || action === 'back') continue;
+
+    if (action === 'disable') {
+      delete mappings[eventName];
+      continue;
+    }
+
+    const soundId = await select({
+      message: `Pick a sound for ${eventName}`,
+      options: sounds.map((id) => ({ value: id, label: id }))
+    });
+
+    if (isCancel(soundId)) continue;
+
+    // quick preview
+    try {
+      await playSound(soundId);
+    } catch {
+      // ignore preview errors
+    }
+
+    mappings[eventName] = soundId;
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('-h') || args.includes('--help')) usage(0);
+
+  const cmd = args[0];
+
+  if (!cmd) {
+    await interactiveSetup();
+    return;
+  }
+
+  if (cmd === 'play') {
+    await cmdPlay();
+    return;
+  }
+
+  if (cmd === 'list-sounds') {
+    await cmdListSounds();
+    return;
+  }
+
+  if (cmd === 'list-events') {
+    await cmdListEvents();
+    return;
+  }
+
+  process.stderr.write(`Unknown command: ${cmd}\n`);
+  usage(1);
+}
+
+main().catch((err) => {
+  process.stderr.write(String(err?.stack || err) + '\n');
+  process.exit(1);
+});

package/src/hooks.js

@@ -0,0 +1,136 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+export const HOOK_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PermissionRequest',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'Notification',
+  'SubagentStart',
+  'SubagentStop',
+  'Stop',
+  'TeammateIdle',
+  'TaskCompleted',
+  'PreCompact',
+  'SessionEnd'
+];
+
+export function configPathForScope(scope, projectDir) {
+  if (scope === 'global') return path.join(os.homedir(), '.claude', 'settings.json');
+  if (scope === 'project') return path.join(projectDir, '.claude', 'settings.json');
+  if (scope === 'projectLocal') return path.join(projectDir, '.claude', 'settings.local.json');
+  throw new Error(`Unknown scope: ${scope}`);
+}
+
+export async function readJsonIfExists(filePath) {
+  try {
+    const raw = await fs.readFile(filePath, 'utf-8');
+    return { ok: true, value: JSON.parse(raw) };
+  } catch (err) {
+    if (err && (err.code === 'ENOENT' || err.code === 'ENOTDIR')) {
+      return { ok: true, value: {} };
+    }
+    return { ok: false, error: err };
+  }
+}
+
+export async function writeJson(filePath, obj) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const text = JSON.stringify(obj, null, 2) + '\n';
+  await fs.writeFile(filePath, text);
+}
+
+const MANAGED_TOKEN = '--managed-by claude-sound';
+
+export function isManagedCommand(command) {
+  return typeof command === 'string' && command.includes(MANAGED_TOKEN);
+}
+
+export function buildManagedCommand({ eventName, soundId }) {
+  // Use --yes to avoid prompts in hook context.
+  // Keep args stable so we can parse back.
+  return `npx --yes claude-sound@latest play --event ${eventName} --sound ${soundId} ${MANAGED_TOKEN}`;
+}
+
+export function extractManagedSoundId(command) {
+  const m = /--sound\s+([^\s]+)/.exec(command || '');
+  return m ? m[1] : null;
+}
+
+export function getExistingManagedMappings(settings) {
+  /** @type {Record<string, string>} */
+  const map = {};
+  const hooks = settings?.hooks;
+  if (!hooks || typeof hooks !== 'object') return map;
+
+  for (const [eventName, groups] of Object.entries(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const g of groups) {
+      const handlers = g?.hooks;
+      if (!Array.isArray(handlers)) continue;
+      for (const h of handlers) {
+        const cmd = h?.command;
+        if (isManagedCommand(cmd)) {
+          const soundId = extractManagedSoundId(cmd);
+          if (soundId) map[eventName] = soundId;
+        }
+      }
+    }
+  }
+
+  return map;
+}
+
+export function applyMappingsToSettings(settings, mappings) {
+  const out = { ...(settings || {}) };
+  out.hooks = { ...(out.hooks || {}) };
+
+  // First: remove all existing managed handlers.
+  for (const [eventName, groups] of Object.entries(out.hooks)) {
+    if (!Array.isArray(groups)) continue;
+
+    const newGroups = [];
+    for (const g of groups) {
+      const handlers = Array.isArray(g?.hooks) ? g.hooks : [];
+      const kept = handlers.filter((h) => !isManagedCommand(h?.command));
+      if (kept.length > 0) {
+        newGroups.push({ ...g, hooks: kept });
+      }
+    }
+
+    if (newGroups.length > 0) out.hooks[eventName] = newGroups;
+    else delete out.hooks[eventName];
+  }
+
+  // Then: add current mappings.
+  // IMPORTANT: do not clobber other user-defined hook groups for the same event.
+  for (const [eventName, soundId] of Object.entries(mappings)) {
+    if (!soundId) continue;
+
+    const handler = {
+      type: 'command',
+      command: buildManagedCommand({ eventName, soundId }),
+      async: true,
+      timeout: 5
+    };
+
+    const group = {
+      matcher: '*',
+      hooks: [handler]
+    };
+
+    const existingGroups = Array.isArray(out.hooks[eventName]) ? out.hooks[eventName] : [];
+    out.hooks[eventName] = [...existingGroups, group];
+  }
+
+  // Clean up if hooks is now empty
+  if (out.hooks && Object.keys(out.hooks).length === 0) {
+    delete out.hooks;
+  }
+
+  return out;
+}

package/src/play.js

@@ -0,0 +1,12 @@
+import { execFile } from 'node:child_process';
+import { resolveSoundPath } from './sounds.js';
+
+export function playSound(soundId) {
+  const file = resolveSoundPath(soundId);
+  return new Promise((resolve, reject) => {
+    execFile('afplay', [file], (err) => {
+      if (err) reject(err);
+      else resolve();
+    });
+  });
+}

package/src/sounds.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export function soundsDir() {
+  return path.resolve(__dirname, '..', 'assets', 'sounds');
+}
+
+export async function listSounds() {
+  const manifestPath = path.join(soundsDir(), 'manifest.json');
+  const raw = await fs.readFile(manifestPath, 'utf-8');
+  /** @type {{id:string,file:string}[]} */
+  const items = JSON.parse(raw);
+  return items.map((it) => it.id);
+}
+
+export function resolveSoundPath(soundId) {
+  return path.join(soundsDir(), `${soundId}.wav`);
+}