claude-code-sounds 1.5.1 → 1.5.3

package/README.md

@@ -4,11 +4,13 @@
 
 # claude-code-sounds
 
+[![npm version](https://img.shields.io/npm/v/claude-code-sounds)](https://www.npmjs.com/package/claude-code-sounds)
+
 **Sound themes for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) lifecycle hooks.**
 
 Plays sound effects when sessions start, prompts are submitted, responses finish, errors occur, and more.
 
-Ships with 12 themes. Bring your own sounds or create new ones.
+Ships with 15 themes. Bring your own sounds or create new ones.
 
 *"Something need doing?"*
 
@@ -24,12 +26,6 @@ The interactive installer checks dependencies, lets you pick a theme, and option
 
 Requires macOS (uses `afplay`) and Node.js 20+.
 
-For scripted or CI usage, skip all prompts with `--yes`:
-
-```bash
-npx claude-code-sounds --yes
-```
-
 <details>
 <summary>Alternative: install from source</summary>
 
@@ -47,8 +43,9 @@ The bash installer requires `jq` (`brew install jq`).
 
 ```bash
 npx claude-code-sounds                    # Interactive install
-npx claude-code-sounds --yes              # Install defaults, skip all prompts
 npx claude-code-sounds --theme portal     # Install a specific theme directly
+npx claude-code-sounds --mix              # Jump to sound assignment grid
+npx claude-code-sounds --yes              # Install defaults, skip all prompts
 npx claude-code-sounds --list             # List available themes
 npx claude-code-sounds --uninstall        # Remove all sounds and hooks
 npx claude-code-sounds --help             # Show help
@@ -58,20 +55,23 @@ npx claude-code-sounds --help             # Show help
 
 | Theme | Sounds | Vibe |
 |---|---|---|
-| **WC3 Orc Peon** (`wc3-peon`) | 57 | *"Something need doing?"* — Peons, Grunts, Shamans, and Grom Hellscream |
-| **Zelda: Ocarina of Time** (`zelda-oot`) | 47 | *"Hey! Listen!"* — Navi, Link, and iconic OOT jingles |
-| **Super Mario Bros** (`mario`) | 47 | *"Let's-a go!"* — Coins, power-ups, and Mario's voice from NES to N64 |
-| **Star Wars** (`star-wars`) | 36 | *"May the Force be with you"* — Lightsabers, R2-D2, and the dark side |
+| **Age of Empires 2** (`aoe2`) | 48 | *"Wololo!"* — Villager taunts, monks, and age advance fanfares |
+| **Call of Duty** (`cod`) | 38 | *"Enemy AC-130 above!"* — Killstreaks, hitmarkers, and Captain Price |
+| **Command & Conquer** (`cnc`) | 52 | *"Construction complete"* — EVA announcements, unit voices, and Red Alert |
+| **Diablo 2** (`diablo2`) | 46 | *"Stay awhile and listen"* — Deckard Cain, item drops, and the Prime Evils |
+| **Halo** (`halo`) | 52 | *"Wake me when you need me"* — Master Chief, Cortana, and the multiplayer announcer |
 | **Metal Gear Solid** (`mgs`) | 40 | *"Kept you waiting, huh?"* — Codec calls, alert sounds, and Snake |
-| **Pokemon Gen 1** (`pokemon-gen1`) | 49 | *"Wild PIKACHU appeared!"* — Cries, battle sounds, and Kanto menus |
+| **Pokemon Gen 3** (`pokemon-gen3`) | 51 | *"A wild TREECKO appeared!"* — GBA battle cries, Hoenn fanfares, and RSE bleeps |
 | **Portal** (`portal`) | 42 | *"Are you still there?"* — Turrets, portal guns, and Aperture Science |
-| **Command & Conquer** (`cnc`) | 72 | *"Construction complete"* — EVA announcements, unit voices, and Red Alert |
-| **Age of Empires 2** (`aoe2`) | 38 | *"Wololo!"* — Villager taunts, monks, and age advance fanfares |
-| **Diablo 2** (`diablo2`) | 41 | *"Stay awhile and listen"* — Deckard Cain, item drops, and the Prime Evils |
-| **Warhammer 40k** (`wh40k`) | 51 | *"For the Emperor!"* — Space Marines, Chaos war cries, and Ork shouts |
-| **StarCraft** (`starcraft`) | 67 | *"Not enough minerals"* — Terran, Protoss, and Zerg voice lines |
+| **Short Circuit** (`short-circuit`) | 41 | *"Number 5 is alive!"* — The lovable sentient robot from the 1986 classic |
+| **Star Wars** (`star-wars`) | 36 | *"May the Force be with you"* — Lightsabers, R2-D2, and the dark side |
+| **StarCraft** (`starcraft`) | 50 | *"Not enough minerals"* — Terran, Protoss, and Zerg voice lines |
+| **Super Mario Bros** (`mario`) | 47 | *"Let's-a go!"* — Coins, power-ups, and Mario's voice from NES to N64 |
+| **Warhammer 40k** (`wh40k`) | 50 | *"For the Emperor!"* — Space Marines, Chaos war cries, and Ork shouts |
+| **WC3 Orc Peon** (`wc3-peon`) | 57 | *"Something need doing?"* — Peons, Grunts, Shamans, and Grom Hellscream |
+| **Zelda: Ocarina of Time** (`zelda-oot`) | 47 | *"Hey! Listen!"* — Navi, Link, and iconic OOT jingles |
 
-Each theme maps sounds across all 11 Claude Code lifecycle events. Preview installed sounds with `./preview.sh`.
+Each theme maps sounds across all 11 Claude Code lifecycle events.
 
 ## Hook Events
 
@@ -124,7 +124,15 @@ Hooks are configured in `~/.claude/settings.json` — each Claude Code lifecycle
 
 ## Customizing
 
-Drop any `.wav` or `.mp3` into the sound directories to add your own clips:
+Re-run with `--mix` to open the sound assignment grid, where you can reassign sounds to hooks, add themes, or preview clips:
+
+```bash
+npx claude-code-sounds --mix
+```
+
+![Sound assignment grid](images/sound-grid.png)
+
+You can also drop any `.wav` or `.mp3` into the sound directories manually:
 
 ```
 ~/.claude/sounds/
@@ -146,4 +154,8 @@ This removes all sound files, the hook script, and the hooks config from `settin
 
 ## Disclaimer
 
-All game audio is property of its respective owners: Blizzard Entertainment (Warcraft, StarCraft, Diablo), Nintendo (Zelda, Mario, Pokemon), Lucasfilm/Disney (Star Wars), Konami (Metal Gear Solid), Valve (Portal), Electronic Arts/Westwood Studios (Command & Conquer), Xbox Game Studios/Ensemble Studios (Age of Empires), and Games Workshop/Relic Entertainment (Warhammer 40,000).
+This project is an unofficial fan project provided free of charge for personal, non-commercial use. It is not affiliated with, endorsed by, or sponsored by any game publisher or rights holder.
+
+All game audio is the property of its respective owners: Blizzard Entertainment (Warcraft, StarCraft, Diablo), Nintendo/Game Freak (Zelda, Mario, Pokemon), Lucasfilm/Disney (Star Wars), Konami (Metal Gear Solid), Valve (Portal), Electronic Arts/Westwood Studios (Command & Conquer), Xbox Game Studios/Ensemble Studios (Age of Empires), Games Workshop/Relic Entertainment (Warhammer 40,000), Xbox Game Studios/Bungie/343 Industries (Halo), Activision/Infinity Ward (Call of Duty), TriStar Pictures (Short Circuit). All trademarks and registered trademarks are the property of their respective owners.
+
+If you are a rights holder and would like content removed, please [open an issue](https://github.com/ryparker/claude-code-sounds/issues) and it will be taken down promptly.

package/bin/cli.js

@@ -2,27 +2,28 @@
 
 const fs = require("fs");
 const path = require("path");
-const os = require("os");
 const { execSync, spawn } = require("child_process");
 const p = require("@clack/prompts");
 const { Prompt } = require("@clack/core");
 const color = require("picocolors");
 
-// ─── Paths ───────────────────────────────────────────────────────────────────
+// ─── Library ─────────────────────────────────────────────────────────────────
 
-const PKG_DIR = path.resolve(__dirname, "..");
-const CLAUDE_DIR = path.join(os.homedir(), ".claude");
-const SOUNDS_DIR = path.join(CLAUDE_DIR, "sounds");
-const HOOKS_DIR = path.join(CLAUDE_DIR, "hooks");
-const SETTINGS_PATH = path.join(CLAUDE_DIR, "settings.json");
-const THEMES_DIR = path.join(PKG_DIR, "themes");
-const INSTALLED_PATH = path.join(SOUNDS_DIR, ".installed.json");
+const lib = require("./lib");
+const paths = lib.defaultPaths();
+const { HOOKS, mkdirp } = lib;
+const { SOUNDS_DIR } = paths;
 
-// ─── Helpers ─────────────────────────────────────────────────────────────────
+// Path-bound wrappers
+const listThemes = () => lib.listThemes(paths);
+const readThemeJson = (name) => lib.readThemeJson(name, paths);
+const resolveThemeSoundPath = (name, file) => lib.resolveThemeSoundPath(name, file, paths);
+const writeInstalled = (data) => lib.writeInstalled(data, paths);
+const detectExistingInstall = () => lib.detectExistingInstall(paths);
+const installSounds = (sel) => lib.installSounds(sel, paths);
+const installHooksConfig = () => lib.installHooksConfig(paths);
 
-function mkdirp(dir) {
-  fs.mkdirSync(dir, { recursive: true });
-}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function exec(cmd, opts = {}) {
   return execSync(cmd, { encoding: "utf-8", stdio: "pipe", ...opts });
@@ -37,70 +38,13 @@ function hasCommand(name) {
   }
 }
 
-function listThemes() {
-  const themes = [];
-  for (const name of fs.readdirSync(THEMES_DIR)) {
-    const themeJson = path.join(THEMES_DIR, name, "theme.json");
-    if (!fs.existsSync(themeJson)) continue;
-    const meta = JSON.parse(fs.readFileSync(themeJson, "utf-8"));
-    let soundCount = 0;
-    if (meta.sounds) {
-      for (const cat of Object.values(meta.sounds)) {
-        soundCount += cat.files.length;
-      }
-    }
-    themes.push({
-      name,
-      description: meta.description || "",
-      display: meta.name || name,
-      soundCount,
-      sources: meta.sources || [],
-    });
-  }
-  return themes;
-}
-
-function readSettings() {
-  if (fs.existsSync(SETTINGS_PATH)) {
-    return JSON.parse(fs.readFileSync(SETTINGS_PATH, "utf-8"));
-  }
-  return {};
-}
-
-function writeSettings(settings) {
-  mkdirp(CLAUDE_DIR);
-  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
-}
-
-function readInstalled() {
-  if (fs.existsSync(INSTALLED_PATH)) {
-    return JSON.parse(fs.readFileSync(INSTALLED_PATH, "utf-8"));
-  }
-  return null;
-}
-
-function writeInstalled(data) {
-  mkdirp(SOUNDS_DIR);
-  fs.writeFileSync(INSTALLED_PATH, JSON.stringify(data, null, 2) + "\n");
-}
-
-function readThemeJson(themeName) {
-  return JSON.parse(
-    fs.readFileSync(path.join(THEMES_DIR, themeName, "theme.json"), "utf-8")
-  );
-}
-
-function resolveThemeSoundPath(themeName, fileName) {
-  return path.join(THEMES_DIR, themeName, "sounds", fileName);
-}
-
 // ─── Preview ─────────────────────────────────────────────────────────────────
 
 let previewProcess = null;
 
 function killPreview() {
   if (previewProcess) {
-    try { previewProcess.kill(); } catch {}
+    try { previewProcess.kill("SIGKILL"); } catch {}
     previewProcess = null;
   }
 }
@@ -108,46 +52,16 @@ function killPreview() {
 function playPreview(filePath) {
   killPreview();
   if (fs.existsSync(filePath)) {
-    previewProcess = spawn("afplay", [filePath], { stdio: "ignore", detached: true });
-    previewProcess.unref();
-    previewProcess.on("exit", () => { previewProcess = null; });
+    const proc = spawn("afplay", [filePath], { stdio: "ignore" });
+    previewProcess = proc;
+    proc.on("exit", () => {
+      if (previewProcess === proc) previewProcess = null;
+    });
   }
 }
 
-// ─── Hooks Config ────────────────────────────────────────────────────────────
-
-const HOOKS_CONFIG = {
-  SessionStart: [{ matcher: "startup", hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" start', timeout: 5 }] }],
-  SessionEnd: [{ hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" end', timeout: 5 }] }],
-  Notification: [
-    { matcher: "permission_prompt", hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" permission', timeout: 5 }] },
-    { matcher: "idle_prompt", hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" idle', timeout: 5 }] },
-  ],
-  Stop: [{ hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" stop', timeout: 5 }] }],
-  SubagentStart: [{ hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" subagent', timeout: 5 }] }],
-  PostToolUseFailure: [{ hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" error', timeout: 5 }] }],
-  UserPromptSubmit: [{ hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" prompt', timeout: 5 }] }],
-  TaskCompleted: [{ hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" task-completed', timeout: 5 }] }],
-  PreCompact: [{ hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" compact', timeout: 5 }] }],
-  TeammateIdle: [{ hooks: [{ type: "command", command: '/bin/bash "$HOME/.claude/hooks/play-sound.sh" teammate-idle', timeout: 5 }] }],
-};
-
 // ─── Sound Grid Prompt ───────────────────────────────────────────────────────
 
-const HOOKS = [
-  { key: "start", abbr: "str", description: "Session starting" },
-  { key: "prompt", abbr: "pmt", description: "User submitted prompt" },
-  { key: "permission", abbr: "prm", description: "Permission prompt" },
-  { key: "stop", abbr: "stp", description: "Done responding" },
-  { key: "subagent", abbr: "sub", description: "Spawning subagent" },
-  { key: "task-completed", abbr: "tsk", description: "Task finished" },
-  { key: "error", abbr: "err", description: "Tool failure" },
-  { key: "compact", abbr: "cmp", description: "Context compaction" },
-  { key: "idle", abbr: "idl", description: "Waiting for input" },
-  { key: "teammate-idle", abbr: "tmt", description: "Teammate went idle" },
-  { key: "end", abbr: "end", description: "Session over" },
-];
-
 /**
  * A 2D grid prompt for assigning sounds to hooks.
  *
@@ -422,59 +336,19 @@ class SoundGrid extends Prompt {
   }
 }
 
-// ─── Install Sounds ──────────────────────────────────────────────────────────
+// ─── Install / Uninstall ─────────────────────────────────────────────────────
 
-/**
- * Copy selected sound files from package to SOUNDS_DIR.
- *
- * @param {Object<string, Array<{themeName: string, fileName: string}>>} selections
- * @returns {number} Total files installed
- */
-function installSounds(selections) {
-  let total = 0;
-
-  for (const [cat, items] of Object.entries(selections)) {
-    const catDir = path.join(SOUNDS_DIR, cat);
-    mkdirp(catDir);
-
-    // Clear existing sounds in this category
-    try {
-      for (const f of fs.readdirSync(catDir)) {
-        if (f.endsWith(".wav") || f.endsWith(".mp3")) {
-          fs.unlinkSync(path.join(catDir, f));
-        }
-      }
-    } catch {}
-
-    // Copy selected sounds
-    for (const item of items) {
-      const srcPath = resolveThemeSoundPath(item.themeName, item.fileName);
-      const destPath = path.join(catDir, item.fileName);
-
-      if (fs.existsSync(srcPath)) {
-        fs.copyFileSync(srcPath, destPath);
-        total++;
-      }
-    }
-  }
-
-  return total;
+async function quickInstall(theme) {
+  const { total, categories } = lib.quickInstall(theme, paths);
+  p.log.success(`Installed ${color.bold(theme.display)} — ${total} sounds across ${categories} hooks.`);
 }
 
-/**
- * Write hooks config and copy play-sound.sh script.
- */
-function installHooksConfig() {
-  mkdirp(HOOKS_DIR);
-
-  const hookSrc = path.join(PKG_DIR, "hooks", "play-sound.sh");
-  const hookDest = path.join(HOOKS_DIR, "play-sound.sh");
-  fs.copyFileSync(hookSrc, hookDest);
-  fs.chmodSync(hookDest, 0o755);
-
-  const settings = readSettings();
-  settings.hooks = HOOKS_CONFIG;
-  writeSettings(settings);
+function uninstallAll() {
+  const removed = lib.uninstallAll(paths);
+  if (removed.sounds) p.log.step("Removed ~/.claude/sounds/");
+  if (removed.hookScript) p.log.step("Removed ~/.claude/hooks/play-sound.sh");
+  if (removed.hooksConfig) p.log.step("Removed hooks from settings.json");
+  if (removed.commands) p.log.step("Removed /mute and /unmute commands");
 }
 
 // ─── Print Summary ───────────────────────────────────────────────────────────
@@ -502,15 +376,21 @@ function showHelp() {
   Usage:
     npx claude-code-sounds              Interactive install
     npx claude-code-sounds --theme mgs  Install a specific theme directly
+    npx claude-code-sounds --mix        Jump straight to the sound grid
     npx claude-code-sounds --yes        Install defaults, skip prompts
     npx claude-code-sounds --list       List available themes
+    npx claude-code-sounds --mute       Mute all sounds
+    npx claude-code-sounds --unmute     Unmute all sounds
     npx claude-code-sounds --uninstall  Remove all sounds and hooks
     npx claude-code-sounds --help       Show this help
 
   Flags:
     -t, --theme <name>  Install a specific theme by name
+    -m, --mix           Jump to sound assignment grid
     -y, --yes           Skip all prompts, use defaults
     -l, --list          List available themes
+        --mute          Mute all sounds
+        --unmute        Unmute all sounds
     -h, --help          Show this help
 `);
 }
@@ -525,26 +405,6 @@ function showList() {
   console.log();
 }
 
-function uninstallAll() {
-  if (fs.existsSync(SOUNDS_DIR)) {
-    fs.rmSync(SOUNDS_DIR, { recursive: true });
-    p.log.step("Removed ~/.claude/sounds/");
-  }
-
-  const hookScript = path.join(HOOKS_DIR, "play-sound.sh");
-  if (fs.existsSync(hookScript)) {
-    fs.unlinkSync(hookScript);
-    p.log.step("Removed ~/.claude/hooks/play-sound.sh");
-  }
-
-  if (fs.existsSync(SETTINGS_PATH)) {
-    const settings = readSettings();
-    delete settings.hooks;
-    writeSettings(settings);
-    p.log.step("Removed hooks from settings.json");
-  }
-}
-
 // ─── Check Dependencies ─────────────────────────────────────────────────────
 
 function checkDependencies() {
@@ -554,76 +414,6 @@ function checkDependencies() {
   }
 }
 
-// ─── Detect Existing Install ─────────────────────────────────────────────────
-
-function detectExistingInstall() {
-  const installed = readInstalled();
-  if (!installed) return null;
-
-  // Support both old format { theme: "name" } and new { themes: [...], mode }
-  const themeNames = installed.themes || (installed.theme ? [installed.theme] : []);
-  if (themeNames.length === 0) return null;
-
-  // Count enabled sounds across all categories
-  let totalEnabled = 0;
-  const allCategories = new Set();
-
-  for (const themeName of themeNames) {
-    try {
-      const theme = readThemeJson(themeName);
-      for (const cat of Object.keys(theme.sounds)) {
-        allCategories.add(cat);
-      }
-    } catch {}
-  }
-
-  for (const cat of allCategories) {
-    const catDir = path.join(SOUNDS_DIR, cat);
-    try {
-      for (const f of fs.readdirSync(catDir)) {
-        if (f.endsWith(".wav") || f.endsWith(".mp3")) totalEnabled++;
-      }
-    } catch {}
-  }
-
-  if (totalEnabled === 0) return null;
-
-  const displays = themeNames.map((n) => {
-    try { return readThemeJson(n).name; } catch { return n; }
-  });
-
-  return {
-    themes: themeNames,
-    themeDisplays: displays,
-    totalEnabled,
-    mode: installed.mode || "quick",
-  };
-}
-
-// ─── Quick Install ───────────────────────────────────────────────────────────
-
-async function quickInstall(theme) {
-  const themeJson = readThemeJson(theme.name);
-  const categories = Object.keys(themeJson.sounds);
-
-  for (const cat of categories) mkdirp(path.join(SOUNDS_DIR, cat));
-
-  // Build selections: all native sounds per category
-  const selections = {};
-  for (const cat of categories) {
-    selections[cat] = themeJson.sounds[cat].files.map((f) => ({
-      themeName: theme.name,
-      fileName: f.name,
-    }));
-  }
-
-  const total = installSounds(selections);
-  writeInstalled({ themes: [theme.name], mode: "quick" });
-  installHooksConfig();
-
-  p.log.success(`Installed ${color.bold(theme.display)} — ${total} sounds across ${categories.length} hooks.`);
-}
-
 // ─── Custom Install ──────────────────────────────────────────────────────────
 
 async function customInstall(selectedThemes) {
@@ -988,6 +778,48 @@ if (flags.has("--help") || flags.has("-h")) {
     p.cancel(err.message);
     process.exit(1);
   });
+} else if (flags.has("--mix") || flags.has("-m")) {
+  (async () => {
+    p.intro(color.bold("claude-code-sounds"));
+    checkDependencies();
+
+    const existing = detectExistingInstall();
+    if (existing) {
+      await reconfigure(existing);
+    } else {
+      const themes = listThemes();
+      if (themes.length === 0) {
+        p.cancel("No themes found in themes/ directory.");
+        process.exit(1);
+      }
+      const themeValues = await p.multiselect({
+        message: "Select themes to include:",
+        options: themes.map((t) => ({
+          value: t.name,
+          label: t.display,
+          hint: `${t.soundCount} sounds — from ${t.sources.join(", ") || "local"}`,
+        })),
+        required: true,
+      });
+      if (p.isCancel(themeValues)) {
+        p.cancel("Cancelled.");
+        process.exit(0);
+      }
+      await customInstall(themes.filter((t) => themeValues.includes(t.name)));
+    }
+
+    p.outro("Start a new Claude Code session to hear it.");
+  })().catch((err) => {
+    killPreview();
+    p.cancel(err.message);
+    process.exit(1);
+  });
+} else if (flags.has("--mute")) {
+  lib.setMuted(true, paths);
+  console.log("  Sounds muted. Run --unmute to re-enable.");
+} else if (flags.has("--unmute")) {
+  lib.setMuted(false, paths);
+  console.log("  Sounds unmuted.");
 } else if (flags.has("--uninstall") || flags.has("--remove")) {
   p.intro(color.bold("claude-code-sounds"));
   uninstallAll();