@mcptoolshop/claude-sfx 0.1.0

package/README.pt-BR.md

@@ -0,0 +1,188 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.md">English</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-sfx/readme.png" width="400" alt="Claude-SFX">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/claude-sfx"><img src="https://img.shields.io/npm/v/claude-sfx" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+  <a href="https://mcp-tool-shop-org.github.io/claude-sfx/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
+</p>
+
+Feedback de áudio procedural para [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Cada chamada de ferramenta, edição de arquivo, pesquisa, envio para o Git e despacho de agente recebe um som distinto — sintetizado a partir de cálculos matemáticos, e não de arquivos de áudio.
+
+## Início Rápido
+
+```bash
+npm install -g claude-sfx
+cd your-project
+claude-sfx init       # install hooks into .claude/settings.json
+claude-sfx demo       # hear all 7 verbs
+```
+
+Pronto. O Claude Code agora emitirá sons enquanto estiver em execução.
+
+## Por que o feedback de áudio?
+
+Quando um agente de IA lê, escreve, pesquisa e implanta em seu nome, você perde a visibilidade. Você está apenas olhando para o texto passando na tela. O feedback de áudio restaura a consciência:
+
+- **Acessibilidade** — ouça as mudanças de estado, erros e conclusões sem precisar observar o terminal.
+- **Fluxo** — saiba se um teste foi aprovado ou se um envio foi concluído sem precisar alternar entre diferentes contextos.
+- **Presença** — o agente parece um colaborador, e não uma caixa preta.
+
+## Os 7 Verbos
+
+Cada ação do Claude Code corresponde a um dos 7 verbos principais. Modificadores (status, escopo, direção) alteram o som sem comprometer a coerência.
+
+| Verbo | Gatilhos | Som |
+| --- | --- | --- |
+| **intake** | `Read`, `WebFetch`, `WebSearch` | Onda senoidal ascendente — algo chegando |
+| **transform** | `Edit` | Pulso texturizado por FM — remodelando |
+| **commit** | `Write`, `NotebookEdit`, `git commit` | Tom de sino agudo — selado |
+| **navigate** | `Grep`, `Glob` | Sinal sonár — escaneando |
+| **execute** | `Bash`, `npm test`, `tsc` | Ruído + tom — ação mecânica |
+| **move** | `mv`, `cp`, criação de subagente | Sopro de vento — deslocamento de ar |
+| **sync** | `git push`, `git pull` | Sopro dramático + âncora tonal |
+
+### Modificadores
+
+```bash
+claude-sfx play navigate --status ok      # bright ping (octave harmonic)
+claude-sfx play navigate --status err     # low detuned ping (dissonance)
+claude-sfx play navigate --status warn    # tremolo ping
+claude-sfx play sync --direction up       # rising whoosh (push)
+claude-sfx play sync --direction down     # falling whoosh (pull)
+claude-sfx play intake --scope remote     # longer tail (distance feel)
+```
+
+### Detecção Inteligente de Bash
+
+O manipulador de eventos inspeciona os comandos Bash para escolher o som correto:
+
+| Comando Bash | Verbo | Status |
+| --- | --- | --- |
+| `git push` | sync (para cima) | com base no código de saída |
+| `git pull` | sync (para baixo) | com base no código de saída |
+| `npm test`, `pytest` | executar | com base no código de saída |
+| `tsc`, `npm run build` | executar | com base no código de saída |
+| `mv`, `cp` | mover | — |
+| `rm` | mover | aviso |
+| tudo o mais | executar | com base no código de saída |
+
+## Perfis
+
+Conjuntos de sons que alteram todo o comportamento com um único parâmetro.
+
+| Perfil | Comportamento |
+| --- | --- |
+| **minimal** (default) | Tons de onda senoidal — sutis, profissionais, para uso diário |
+| **retro** | Sons de onda quadrada em 8 bits — divertidos, mas controlados |
+
+```bash
+claude-sfx demo --profile retro           # hear retro palette
+claude-sfx preview minimal                # audition all sounds + modifiers
+claude-sfx config set profile retro       # change default globally
+claude-sfx config repo retro              # use retro in current directory only
+```
+
+### Perfis Personalizados
+
+Copie `profiles/minimal.json`, edite os parâmetros de síntese e carregue-o:
+
+```bash
+claude-sfx play navigate --profile ./my-profile.json
+```
+
+Cada número no arquivo JSON corresponde diretamente ao motor de síntese — forma de onda, frequência, duração, envelope (ADSR), profundidade de modulação por frequência (FM), largura de banda, ganho.
+
+## Anti-Irritação
+
+O que diferencia um produto de um brinquedo.
+
+| Recurso | Comportamento |
+| --- | --- |
+| **Debounce** | O mesmo verbo dentro de 200ms → um som |
+| **Rate limit** | Máximo de 8 sons em uma janela de 10 segundos |
+| **Quiet hours** | Todos os sons são suprimidos durante as horas configuradas |
+| **Mute** | Alternância instantânea, persiste após a reinicialização da sessão |
+| **Volume** | Controle de ganho de 0 a 100 |
+| **Per-verb disable** | Desative verbos específicos que você não deseja |
+
+```bash
+claude-sfx mute                            # instant silence
+claude-sfx unmute
+claude-sfx volume 40                       # quieter
+claude-sfx config set quiet-start 22:00    # quiet after 10pm
+claude-sfx config set quiet-end 07:00      # until 7am
+claude-sfx disable navigate                # no more search pings
+claude-sfx enable navigate                 # bring it back
+```
+
+## Ambiente (Operações de Longa Duração)
+
+Para comandos que levam um tempo (compilações, implantações, grandes conjuntos de testes):
+
+```bash
+claude-sfx ambient-start     # low drone fades in
+# ... operation runs ...
+claude-sfx ambient-resolve   # drone stops, resolution stinger plays
+claude-sfx ambient-stop      # stop drone silently (no stinger)
+```
+
+## Sons da Sessão
+
+```bash
+claude-sfx session-start     # two-note ascending chime (boot)
+claude-sfx session-end       # two-note descending chime (closure)
+```
+
+## Todos os Comandos
+
+```
+Setup:
+  init                            Install hooks into .claude/settings.json
+  uninstall                       Remove hooks
+
+Playback:
+  play <verb> [options]           Play a sound (goes through guard)
+  demo [--profile <name>]         Play all 7 verbs
+  preview [profile]               Audition all sounds in a profile
+  session-start / session-end     Chimes
+  ambient-start / ambient-resolve / ambient-stop
+
+Config:
+  mute / unmute                   Toggle all sounds
+  volume [0-100]                  Get or set volume
+  config                          Print current config
+  config set <key> <value>        Set a value
+  config reset                    Reset to defaults
+  config repo <profile|clear>     Per-directory profile override
+  disable / enable <verb>         Toggle specific verbs
+  export [dir] [--profile]        Export all sounds as .wav files
+```
+
+## Como Funciona
+
+Nenhum arquivo de áudio. Cada som é sintetizado em tempo de execução a partir de cálculos matemáticos:
+
+- **Osciladores** — senoidal, quadrado, dente de serra, triangular, ruído branco
+- **Envelopes ADSR** — ataque, decaimento, sustentação, liberação
+- **Síntese FM** — modulação de frequência para texturas
+- **Filtro de variável de estado** — ruído filtrado em banda para efeitos sonoros
+- **Varreduras de frequência** — interpolação linear para movimento
+- **Limitador de volume** — compressão "soft-knee", limite máximo
+
+O pacote completo tem aproximadamente 2.800 linhas de código TypeScript e não possui dependências para produção. Os sons são gerados como buffers PCM, codificados em WAV na memória e reproduzidos através do reprodutor de áudio nativo do sistema operacional (PowerShell no Windows, afplay no macOS, aplay no Linux).
+
+## Requisitos:
+
+- Node.js 18 ou superior
+- Claude Code
+- Saída de áudio do sistema (alto-falantes ou fones de ouvido)
+
+## Licença:
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,188 @@
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.md">English</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-sfx/readme.png" width="400" alt="Claude-SFX">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/claude-sfx"><img src="https://img.shields.io/npm/v/claude-sfx" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+  <a href="https://mcp-tool-shop-org.github.io/claude-sfx/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
+</p>
+
+对于 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)，我们提供了程序化的音频反馈。 每次工具调用、文件编辑、搜索、git推送以及代理任务都会产生不同的声音，这些声音是通过数学算法合成的，而不是音频文件。
+
+## 快速开始
+
+```bash
+npm install -g claude-sfx
+cd your-project
+claude-sfx init       # install hooks into .claude/settings.json
+claude-sfx demo       # hear all 7 verbs
+```
+
+就此完成了。现在，Claude Code 在工作时会发出声音。
+
+## 为什么使用音频反馈？
+
+当 AI 代理代表您读取、编写、搜索和部署时，您会失去可见性。 您只是盯着屏幕上滚动的文本。 音频反馈可以恢复您的意识：
+
+- **可访问性**：无需观看终端，即可听到状态变化、错误和完成情况。
+- **流畅性**：无需切换上下文，即可知道测试是否通过或推送是否成功。
+- **沉浸感**：代理感觉更像是一个协作者，而不是一个黑盒子。
+
+## 7 种动词
+
+Claude Code 的每个操作都对应于 7 种核心动词中的一种。 修饰符（状态、范围、方向）会改变声音，但不会破坏其连贯性。
+
+| 动词 | 触发器 | 声音 |
+| --- | --- | --- |
+| **intake** | `Read`, `WebFetch`, `WebSearch` | 逐渐上升的正弦波——表示即将到来 |
+| **transform** | `Edit` | FM 调制脉冲——表示重塑 |
+| **commit** | `Write`, `NotebookEdit`, `git commit` | 清晰的敲击声——表示已完成 |
+| **navigate** | `Grep`, `Glob` | 声纳回声——表示扫描 |
+| **execute** | `Bash`, `npm test`, `tsc` | 噪声爆发 + 声音——表示机械动作 |
+| **move** | `mv`、`cp`、子代理启动 | 气流声——表示空气移动 |
+| **sync** | `git push`, `git pull` | 戏剧性的气流声 + 音调锚 |
+
+### 修饰符
+
+```bash
+claude-sfx play navigate --status ok      # bright ping (octave harmonic)
+claude-sfx play navigate --status err     # low detuned ping (dissonance)
+claude-sfx play navigate --status warn    # tremolo ping
+claude-sfx play sync --direction up       # rising whoosh (push)
+claude-sfx play sync --direction down     # falling whoosh (pull)
+claude-sfx play intake --scope remote     # longer tail (distance feel)
+```
+
+### 智能 Bash 检测
+
+处理程序会检查 Bash 命令，以选择正确的声音：
+
+| Bash 命令 | 动词 | 状态 |
+| --- | --- | --- |
+| `git push` | sync (向上) | 来自退出码 |
+| `git pull` | sync (向下) | 来自退出码 |
+| `npm test`, `pytest` | execute (执行) | 来自退出码 |
+| `tsc`, `npm run build` | execute (执行) | 来自退出码 |
+| `mv`, `cp` | move (移动) | — |
+| `rm` | move (移动) | warn (警告) |
+| 其他所有情况 | execute (执行) | 来自退出码 |
+
+## 配置文件
+
+这些配置文件会改变整个声音，只需一个标志即可。
+
+| 配置文件 | 声音风格 |
+| --- | --- |
+| **minimal** (default) | 正弦波声音——微妙、专业、日常使用 |
+| **retro** | 方波 8 位声音——有趣但可控 |
+
+```bash
+claude-sfx demo --profile retro           # hear retro palette
+claude-sfx preview minimal                # audition all sounds + modifiers
+claude-sfx config set profile retro       # change default globally
+claude-sfx config repo retro              # use retro in current directory only
+```
+
+### 自定义配置文件
+
+复制 `profiles/minimal.json`，编辑合成参数，然后加载它：
+
+```bash
+claude-sfx play navigate --profile ./my-profile.json
+```
+
+JSON 中的每个数字都直接映射到合成引擎，包括波形、频率、持续时间、包络（ADSR）、FM 深度、带宽和增益。
+
+## 防厌烦
+
+区分产品和玩具的关键。
+
+| 功能 | 行为 |
+| --- | --- |
+| **Debounce** | 相同动词在 200 毫秒内出现 → 产生一个声音 |
+| **Rate limit** | 每 10 秒最多 8 个声音 |
+| **Quiet hours** | 在配置的时间段内，所有声音都会被抑制 |
+| **Mute** | 即时切换，重启会话后仍然有效 |
+| **Volume** | 0–100 增益控制 |
+| **Per-verb disable** | 可以关闭您不想听到的特定动词的声音 |
+
+```bash
+claude-sfx mute                            # instant silence
+claude-sfx unmute
+claude-sfx volume 40                       # quieter
+claude-sfx config set quiet-start 22:00    # quiet after 10pm
+claude-sfx config set quiet-end 07:00      # until 7am
+claude-sfx disable navigate                # no more search pings
+claude-sfx enable navigate                 # bring it back
+```
+
+## 环境声音（长时间运行的操作）
+
+对于需要一段时间才能完成的命令（构建、部署、大型测试套件）：
+
+```bash
+claude-sfx ambient-start     # low drone fades in
+# ... operation runs ...
+claude-sfx ambient-resolve   # drone stops, resolution stinger plays
+claude-sfx ambient-stop      # stop drone silently (no stinger)
+```
+
+## 会话声音
+
+```bash
+claude-sfx session-start     # two-note ascending chime (boot)
+claude-sfx session-end       # two-note descending chime (closure)
+```
+
+## 所有命令
+
+```
+Setup:
+  init                            Install hooks into .claude/settings.json
+  uninstall                       Remove hooks
+
+Playback:
+  play <verb> [options]           Play a sound (goes through guard)
+  demo [--profile <name>]         Play all 7 verbs
+  preview [profile]               Audition all sounds in a profile
+  session-start / session-end     Chimes
+  ambient-start / ambient-resolve / ambient-stop
+
+Config:
+  mute / unmute                   Toggle all sounds
+  volume [0-100]                  Get or set volume
+  config                          Print current config
+  config set <key> <value>        Set a value
+  config reset                    Reset to defaults
+  config repo <profile|clear>     Per-directory profile override
+  disable / enable <verb>         Toggle specific verbs
+  export [dir] [--profile]        Export all sounds as .wav files
+```
+
+## 工作原理
+
+没有音频文件。 每次声音都是在运行时通过数学算法合成的：
+
+- **振荡器** — 正弦波、方波、锯齿波、三角波、白噪声
+- **ADSR 包络线** — 攻击 (attack)、衰减 (decay)、维持 (sustain)、释放 (release)
+- **FM 综合** — 用于产生纹理的频率调制
+- **状态变量滤波器** — 用于产生“嗖嗖”声的带通滤波噪声
+- **频率扫描** — 用于产生运动效果的线性插值
+- **响度限制器** — 软压缩、硬限位
+
+整个软件包包含约 2800 行 TypeScript 代码，且没有任何生产依赖。声音以 PCM 缓冲区生成，在内存中编码为 WAV 格式，并通过操作系统自带的音频播放器播放（Windows 上的 PowerShell，macOS 上的 afplay，Linux 上的 aplay）。
+
+## 需求
+
+- Node.js 18+
+- Claude Code
+- 系统音频输出（扬声器或耳机）
+
+## 许可证
+
+[MIT](LICENSE)

package/dist/ambient.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ambient drone system for long-running operations.
+ * Starts a low background drone that loops until resolved.
+ *
+ * Flow: claude-sfx ambient-start → drone plays in background
+ *       claude-sfx ambient-resolve → drone stops, stinger plays
+ *
+ * Implementation: writes a PID file so `ambient-resolve` can find and kill the drone.
+ */
+import type { Profile } from "./profiles.js";
+/** Check if an ambient drone is currently running. */
+export declare function isAmbientRunning(): boolean;
+/**
+ * Start the ambient drone in a background process.
+ * The drone loops a WAV file using the system player until killed.
+ */
+export declare function startAmbient(profile: Profile): {
+    started: boolean;
+    pid?: number;
+};
+/** Stop the ambient drone and play the resolution stinger. */
+export declare function resolveAmbient(profile: Profile): {
+    resolved: boolean;
+};
+/** Stop the ambient drone without playing the stinger. */
+export declare function stopAmbient(): {
+    stopped: boolean;
+};

package/dist/ambient.js

@@ -0,0 +1,179 @@
+/**
+ * Ambient drone system for long-running operations.
+ * Starts a low background drone that loops until resolved.
+ *
+ * Flow: claude-sfx ambient-start → drone plays in background
+ *       claude-sfx ambient-resolve → drone stops, stinger plays
+ *
+ * Implementation: writes a PID file so `ambient-resolve` can find and kill the drone.
+ */
+import { writeFileSync, readFileSync, unlinkSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn, execSync } from "node:child_process";
+import { generateAmbientChunk, generateAmbientResolve } from "./verbs.js";
+import { encodeWav } from "./synth.js";
+import { playSync } from "./player.js";
+const PID_FILE = join(tmpdir(), "claude-sfx-ambient.pid");
+const DRONE_WAV = join(tmpdir(), "claude-sfx-drone.wav");
+/** Check if an ambient drone is currently running. */
+export function isAmbientRunning() {
+    if (!existsSync(PID_FILE))
+        return false;
+    try {
+        const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
+        // Check if process is alive (signal 0 = existence check)
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        // Process dead or PID file stale — clean up
+        try {
+            unlinkSync(PID_FILE);
+        }
+        catch { /* ignore */ }
+        return false;
+    }
+}
+/**
+ * Start the ambient drone in a background process.
+ * The drone loops a WAV file using the system player until killed.
+ */
+export function startAmbient(profile) {
+    if (isAmbientRunning()) {
+        return { started: false };
+    }
+    // Generate the drone chunk WAV
+    const chunk = generateAmbientChunk(profile);
+    const wavData = encodeWav(chunk);
+    writeFileSync(DRONE_WAV, wavData);
+    // Spawn a looping player process
+    const platform = process.platform;
+    let child;
+    if (platform === "win32") {
+        // PowerShell loop: plays the WAV repeatedly until killed
+        child = spawn("powershell", [
+            "-NoProfile",
+            "-Command",
+            `while($true){(New-Object Media.SoundPlayer '${DRONE_WAV}').PlaySync()}`,
+        ], {
+            stdio: "ignore",
+            detached: true,
+        });
+    }
+    else if (platform === "darwin") {
+        // macOS: loop with afplay
+        child = spawn("bash", [
+            "-c",
+            `while true; do afplay "${DRONE_WAV}"; done`,
+        ], {
+            stdio: "ignore",
+            detached: true,
+        });
+    }
+    else {
+        // Linux: loop with aplay/paplay
+        const player = (() => {
+            try {
+                execSync("which paplay", { stdio: "ignore" });
+                return "paplay";
+            }
+            catch {
+                return "aplay -q";
+            }
+        })();
+        child = spawn("bash", [
+            "-c",
+            `while true; do ${player} "${DRONE_WAV}"; done`,
+        ], {
+            stdio: "ignore",
+            detached: true,
+        });
+    }
+    child.unref();
+    if (child.pid) {
+        writeFileSync(PID_FILE, String(child.pid));
+        return { started: true, pid: child.pid };
+    }
+    return { started: false };
+}
+/** Stop the ambient drone and play the resolution stinger. */
+export function resolveAmbient(profile) {
+    if (!existsSync(PID_FILE)) {
+        return { resolved: false };
+    }
+    try {
+        const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
+        // Kill the drone process tree
+        if (process.platform === "win32") {
+            try {
+                execSync(`taskkill /PID ${pid} /T /F`, { stdio: "ignore" });
+            }
+            catch { /* already dead */ }
+        }
+        else {
+            try {
+                // Kill the process group (negative PID)
+                process.kill(-pid, "SIGTERM");
+            }
+            catch {
+                try {
+                    process.kill(pid, "SIGTERM");
+                }
+                catch { /* already dead */ }
+            }
+        }
+    }
+    catch {
+        // PID parse error or kill error — move on
+    }
+    // Clean up
+    try {
+        unlinkSync(PID_FILE);
+    }
+    catch { /* ignore */ }
+    try {
+        unlinkSync(DRONE_WAV);
+    }
+    catch { /* ignore */ }
+    // Play the resolution stinger
+    const stinger = generateAmbientResolve(profile);
+    playSync(stinger);
+    return { resolved: true };
+}
+/** Stop the ambient drone without playing the stinger. */
+export function stopAmbient() {
+    if (!existsSync(PID_FILE)) {
+        return { stopped: false };
+    }
+    try {
+        const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
+        if (process.platform === "win32") {
+            try {
+                execSync(`taskkill /PID ${pid} /T /F`, { stdio: "ignore" });
+            }
+            catch { /* already dead */ }
+        }
+        else {
+            try {
+                process.kill(-pid, "SIGTERM");
+            }
+            catch {
+                try {
+                    process.kill(pid, "SIGTERM");
+                }
+                catch { /* already dead */ }
+            }
+        }
+    }
+    catch { /* ignore */ }
+    try {
+        unlinkSync(PID_FILE);
+    }
+    catch { /* ignore */ }
+    try {
+        unlinkSync(DRONE_WAV);
+    }
+    catch { /* ignore */ }
+    return { stopped: true };
+}

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * claude-sfx CLI
+ * Procedural audio feedback for Claude Code.
+ */
+export {};