cvox 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# cvox
+
+[![npm version](https://img.shields.io/npm/v/cvox.svg)](https://www.npmjs.com/package/cvox)
+
+Voice notifications for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) hooks. Get spoken alerts when Claude needs permission or finishes a task — so you can step away from the screen.
+
+## Features
+
+- Cross-platform TTS: macOS (`say`), Linux (`espeak`), Windows (SAPI via PowerShell)
+- Two hook events: permission prompt and task completion
+- Three-layer config merging: defaults → `~/.cvox.json` → project `.cvox.json`
+- Idempotent installation — safe to run multiple times
+- `{project}` placeholder in messages, auto-detected from directory name
+
+## Quick Start
+
+```bash
+# One-liner: install hooks into your project
+npx cvox init
+
+# Or install globally
+npm install -g cvox
+cvox init
+
+# Install hooks globally (applies to all projects)
+cvox init --global
+```
+
+That's it. Claude Code will now speak to you when it needs attention.
+
+## Configuration
+
+Create a `.cvox.json` in your project root or home directory (`~/.cvox.json`) to customize behavior:
+
+```json
+{
+  "project": "my-app",
+  "hooks": {
+    "notification": {
+      "enabled": true,
+      "message": "{project} needs permission"
+    },
+    "stop": {
+      "enabled": true,
+      "message": "{project} task complete"
+    }
+  },
+  "tts": {
+    "enabled": true
+  }
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `project` | string | directory name | Project name used in `{project}` placeholder |
+| `hooks.notification.enabled` | boolean | `true` | Enable voice alert on permission prompts |
+| `hooks.notification.message` | string | `"{project} needs permission"` | Message spoken on permission prompt |
+| `hooks.stop.enabled` | boolean | `true` | Enable voice alert on task completion |
+| `hooks.stop.message` | string | `"{project} task completed"` | Message spoken on task completion |
+| `tts.enabled` | boolean | `true` | Enable/disable TTS globally |
+
+Config files are merged with deep merge — you only need to specify the fields you want to override.
+
+## How It Works
+
+1. `cvox init` injects hooks into Claude Code's `settings.json`
+2. When Claude Code triggers a hook event (permission prompt or stop), it pipes a JSON payload via stdin to `cvox notify`
+3. `cvox notify` reads the event, loads your config, and calls the platform TTS engine to speak the message
+
+## License
+
+MIT

package/dist/commands/init.js

@@ -0,0 +1,14 @@
+import { generateHooksConfig } from "../hooks/config.js";
+import { getSettingsPath, readSettings, writeSettings, mergeHooks, } from "../utils/settings.js";
+export function initCommand(options) {
+    const isGlobal = options.global ?? false;
+    const settingsPath = getSettingsPath(isGlobal);
+    const settings = readSettings(settingsPath);
+    const cvoxHooks = generateHooksConfig();
+    const merged = mergeHooks(settings, cvoxHooks);
+    writeSettings(settingsPath, merged);
+    const target = isGlobal ? "全局" : "项目";
+    console.log(`cvox: 已配置 ${target} hooks → ${settingsPath}`);
+    console.log("  - Notification (permission_prompt)");
+    console.log("  - Stop");
+}

package/dist/commands/notify.js

@@ -0,0 +1,78 @@
+import { execFile } from "child_process";
+import { loadConfig } from "../utils/config.js";
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+        if (process.stdin.isTTY) {
+            resolve("");
+        }
+    });
+}
+function mapEventName(hookEventName) {
+    const map = {
+        Notification: "notification",
+        Stop: "stop",
+    };
+    return map[hookEventName] ?? null;
+}
+function speak(message, config) {
+    const { tts } = config;
+    if (!tts.enabled)
+        return;
+    const engine = detectEngine();
+    switch (engine) {
+        case "say": {
+            execFile("say", [message], () => { });
+            break;
+        }
+        case "espeak": {
+            execFile("espeak", [message], () => { });
+            break;
+        }
+        case "sapi": {
+            const ps = `Add-Type -AssemblyName System.Speech; ` +
+                `$s = New-Object System.Speech.Synthesis.SpeechSynthesizer; ` +
+                `$s.Speak('${message.replace(/'/g, "''")}')`;
+            execFile("powershell", ["-Command", ps], () => { });
+            break;
+        }
+    }
+}
+function detectEngine() {
+    switch (process.platform) {
+        case "darwin":
+            return "say";
+        case "win32":
+            return "sapi";
+        default:
+            return "espeak";
+    }
+}
+export async function notifyCommand() {
+    const raw = await readStdin();
+    if (!raw.trim())
+        return;
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        return;
+    }
+    const eventName = input.hook_event_name;
+    if (!eventName)
+        return;
+    const eventKey = mapEventName(eventName);
+    if (!eventKey)
+        return;
+    const cwd = input.cwd || process.cwd();
+    const config = loadConfig(cwd);
+    const hookConfig = config.hooks[eventKey];
+    if (!hookConfig.enabled)
+        return;
+    const message = hookConfig.message.replace(/\{project\}/g, config.project);
+    speak(message, config);
+}

package/dist/hooks/config.js

@@ -0,0 +1,23 @@
+export function generateHooksConfig() {
+    const notifyHook = {
+        type: "command",
+        command: "cvox notify",
+        async: true,
+    };
+    return {
+        hooks: {
+            Notification: [
+                {
+                    matcher: "permission_prompt",
+                    hooks: [notifyHook],
+                },
+            ],
+            Stop: [
+                {
+                    matcher: "",
+                    hooks: [{ ...notifyHook }],
+                },
+            ],
+        },
+    };
+}

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { initCommand } from "./commands/init.js";
+import { notifyCommand } from "./commands/notify.js";
+const program = new Command();
+program
+    .name("cvox")
+    .description("Claude Voice Notifications")
+    .version("1.0.0");
+program
+    .command("init")
+    .description("向 Claude Code settings 注入 hooks")
+    .option("--global", "写入全局 ~/.claude/settings.json")
+    .action(initCommand);
+program
+    .command("notify")
+    .description("被 hooks 调用，读取 stdin 播放语音通知")
+    .action(notifyCommand);
+program.parse();

package/dist/utils/config.js

@@ -0,0 +1,62 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+export const DEFAULT_CONFIG = {
+    project: "",
+    hooks: {
+        notification: {
+            enabled: true,
+            message: "{project} needs permission",
+        },
+        stop: {
+            enabled: true,
+            message: "{project} task completed",
+        },
+    },
+    tts: {
+        enabled: true,
+    },
+    desktop: {
+        enabled: false,
+    },
+};
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        if (source[key] &&
+            typeof source[key] === "object" &&
+            !Array.isArray(source[key]) &&
+            target[key] &&
+            typeof target[key] === "object") {
+            result[key] = deepMerge(target[key], source[key]);
+        }
+        else {
+            result[key] = source[key];
+        }
+    }
+    return result;
+}
+function tryReadJson(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+export function loadConfig(cwd) {
+    const projectConfig = tryReadJson(path.join(cwd, ".cvox.json"));
+    const globalConfig = tryReadJson(path.join(os.homedir(), ".cvox.json"));
+    let config = { ...DEFAULT_CONFIG };
+    if (globalConfig) {
+        config = deepMerge(config, globalConfig);
+    }
+    if (projectConfig) {
+        config = deepMerge(config, projectConfig);
+    }
+    if (!config.project) {
+        config.project = path.basename(cwd);
+    }
+    return config;
+}

package/dist/utils/settings.js

@@ -0,0 +1,46 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+const CVOX_MARKER = "cvox notify";
+export function getSettingsPath(global, cwd) {
+    if (global) {
+        return path.join(os.homedir(), ".claude", "settings.json");
+    }
+    return path.join(cwd || process.cwd(), ".claude", "settings.local.json");
+}
+export function readSettings(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+export function writeSettings(filePath, settings) {
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(settings, null, 2) + "\n");
+}
+function isCvoxHook(hook) {
+    return (hook &&
+        typeof hook.command === "string" &&
+        hook.command.includes(CVOX_MARKER));
+}
+function isCvoxMatcher(matcher) {
+    return (matcher &&
+        Array.isArray(matcher.hooks) &&
+        matcher.hooks.some(isCvoxHook));
+}
+export function mergeHooks(settings, cvoxHooks) {
+    const result = { ...settings };
+    const existingHooks = result.hooks || {};
+    const merged = { ...existingHooks };
+    for (const [eventName, cvoxMatchers] of Object.entries(cvoxHooks.hooks)) {
+        const existing = merged[eventName] || [];
+        const filtered = existing.filter((m) => !isCvoxMatcher(m));
+        merged[eventName] = [...filtered, ...cvoxMatchers];
+    }
+    result.hooks = merged;
+    return result;
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "cvox",
+  "version": "1.0.0",
+  "description": "Claude Voice Notifications - voice alerts for Claude Code hooks",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "cvox": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "hooks",
+    "tts",
+    "voice",
+    "notifications",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lmk123/cvox.git"
+  },
+  "homepage": "https://github.com/lmk123/cvox#readme",
+  "bugs": {
+    "url": "https://github.com/lmk123/cvox/issues"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.3"
+  }
+}