claude-hook-notify 1.0.0

package/README.md

@@ -0,0 +1,120 @@
+# 🔔 claude-hook-notify
+
+Claude Code 任务完成桌面通知 — 一键安装，跨平台支持 (macOS / Linux / Windows)
+
+> 不用再盯着终端等 Claude Code 完成了。任务一完，桌面通知自动弹出。
+
+## 快速开始
+
+```bash
+npx claude-hook-notify setup
+```
+
+就这一行。重启 Claude Code 后即可生效。
+
+## 效果
+
+当 Claude Code 完成任务时，你会收到系统原生桌面通知：
+
+```
+┌──────────────────────────────────────┐
+│  🔔 Claude Code 完成 (my-project)   │
+│  已完成代码重构和测试                  │
+└──────────────────────────────────────┘
+```
+
+API 错误中断时：
+
+```
+┌──────────────────────────────────────────────────┐
+│  ⚠ Claude Code 错误: 请求频率限制 (my-project)    │
+│  Rate limit exceeded: too many requests           │
+└──────────────────────────────────────────────────┘
+```
+
+## 命令
+
+### 安装
+
+```bash
+# 全局安装（所有项目生效，默认）
+npx claude-hook-notify setup
+
+# 仅当前项目
+npx claude-hook-notify setup --local
+
+# 指定监听事件
+npx claude-hook-notify setup --events Stop,TaskCompleted
+```
+
+### 卸载
+
+```bash
+npx claude-hook-notify uninstall
+
+# 卸载项目级配置
+npx claude-hook-notify uninstall --local
+```
+
+### 手动发送通知（测试用）
+
+```bash
+# 测试通知
+npx claude-hook-notify notify --event Stop --dry-run
+
+# 自定义通知
+npx claude-hook-notify notify --title "构建完成" --message "所有测试通过"
+```
+
+## 监听事件
+
+| 事件              | 触发时机                         | 音效 (macOS) |
+| ----------------- | -------------------------------- | ------------ |
+| `Stop`            | Claude Code 完成一次响应         | Glass        |
+| `TaskCompleted`   | 子任务被标记为完成               | Hero         |
+| `Notification`    | Claude Code 需要你注意（等输入） | Ping         |
+| `StopFailure`     | API 错误导致中断（限流/认证/服务器错误等） | Sosumi       |
+
+> **注意**: `Stop` 事件在响应因 token 限制被截断时会显示特殊提示。
+
+也可以添加额外事件：
+
+```bash
+npx claude-hook-notify setup --events Stop,TaskCompleted,Notification,StopFailure,PostToolUseFailure,SubagentStop
+```
+
+## 平台支持
+
+| 平台    | 通知方式             | 依赖                                          |
+| ------- | -------------------- | --------------------------------------------- |
+| macOS   | `osascript`          | 无（系统自带）                                |
+| macOS   | `terminal-notifier`  | 可选: `brew install terminal-notifier`（更好） |
+| Linux   | `notify-send`        | `sudo apt-get install libnotify-bin`          |
+| Windows | PowerShell           | 无（系统自带）                                |
+
+## 原理
+
+安装时会在 `~/.claude/settings.json` 中添加 hooks 配置。当对应事件触发时，Claude Code 会自动执行 `npx claude-hook-notify notify --event <事件名>`，脚本会读取 hook 传入的上下文信息（任务名称、最后的 assistant 消息等），然后通过系统原生 API 发送桌面通知。
+
+## 编程接口
+
+也可以作为库使用：
+
+```js
+const { sendNotification } = require("claude-hook-notify");
+
+await sendNotification({
+  event: "Stop",
+  title: "构建完成",
+  message: "所有 42 个测试通过",
+});
+```
+
+## 已知限制
+
+- **Ctrl+C 用户中断**: 用户手动按 Ctrl+C 取消时不会触发任何 hook 事件，因此无法发送通知。
+- **网络完全断开**: 如果网络完全断开导致 Claude Code 进程本身退出，hook 可能无法执行。API 层面的网络错误（如超时）会通过 `StopFailure` 的 `server_error` 类型捕获。
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "claude-hook-notify",
+  "version": "1.0.0",
+  "description": "🔔 Claude Code 任务完成桌面通知 — 一键安装，跨平台支持",
+  "main": "src/index.js",
+  "bin": {
+    "claude-hook-notify": "src/cli.js"
+  },
+  "scripts": {
+    "test": "node src/cli.js notify --event Stop --dry-run"
+  },
+  "keywords": [
+    "claude-code",
+    "hooks",
+    "notification",
+    "desktop-notification",
+    "osascript",
+    "notify-send",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ]
+}

package/src/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+const { setup } = require("./setup");
+const { uninstall } = require("./setup");
+const { sendNotification } = require("./notify");
+
+const HELP = `
+  claude-hook-notify — 🔔 Claude Code 任务完成桌面通知
+
+  用法:
+    claude-hook-notify setup       一键安装 hooks 配置
+    claude-hook-notify uninstall   移除已安装的 hooks 配置
+    claude-hook-notify notify      发送通知（由 hook 自动调用）
+    claude-hook-notify help        显示帮助信息
+
+  setup 选项:
+    --global                 安装到全局配置 ~/.claude/settings.json（默认）
+    --local                  安装到当前项目 .claude/settings.json
+    --events <事件列表>      要监听的事件，逗号分隔
+                             默认: Stop,TaskCompleted,Notification,StopFailure
+
+  notify 选项:
+    --event <事件名>         事件类型 (Stop/TaskCompleted/Notification/...)
+    --title <标题>           自定义通知标题
+    --message <消息>         自定义通知消息
+    --sound <音效>           macOS 音效名称 (默认: Glass)
+    --dry-run                仅打印通知内容，不实际发送
+
+  示例:
+    npx claude-hook-notify setup
+    npx claude-hook-notify setup --events Stop,TaskCompleted
+    npx claude-hook-notify uninstall
+`;
+
+function parseArgs(args) {
+  const parsed = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith("--")) {
+      const key = args[i].slice(2);
+      if (
+        key === "dry-run" ||
+        key === "global" ||
+        key === "local" ||
+        key === "help"
+      ) {
+        parsed[key] = true;
+      } else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        parsed[key] = args[++i];
+      } else {
+        parsed[key] = true;
+      }
+    } else {
+      parsed._.push(args[i]);
+    }
+  }
+  return parsed;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const command = args._[0];
+
+  if (!command || command === "help" || args.help) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (command === "setup") {
+    const scope = args.local ? "local" : "global";
+    const events = args.events
+      ? args.events.split(",").map((e) => e.trim())
+      : ["Stop", "TaskCompleted", "Notification", "StopFailure"];
+    await setup({ scope, events });
+    return;
+  }
+
+  if (command === "uninstall") {
+    const scope = args.local ? "local" : "global";
+    await uninstall({ scope });
+    return;
+  }
+
+  if (command === "notify") {
+    let input = {};
+    // 从 stdin 读取 hook JSON 数据（非交互模式）
+    if (!process.stdin.isTTY) {
+      try {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+          chunks.push(chunk);
+        }
+        const raw = Buffer.concat(chunks).toString("utf-8").trim();
+        if (raw) input = JSON.parse(raw);
+      } catch {
+        // stdin 为空或非 JSON，忽略
+      }
+    }
+
+    await sendNotification({
+      event: args.event || "Stop",
+      title: args.title,
+      message: args.message,
+      sound: args.sound,
+      dryRun: !!args["dry-run"],
+      hookInput: input,
+    });
+    return;
+  }
+
+  console.error(`未知命令: ${command}\n运行 claude-hook-notify help 查看帮助`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error("错误:", err.message);
+  process.exit(1);
+});

package/src/index.js

@@ -0,0 +1,4 @@
+const { sendNotification, EVENT_CONFIG } = require("./notify");
+const { setup, uninstall } = require("./setup");
+
+module.exports = { sendNotification, EVENT_CONFIG, setup, uninstall };

package/src/notify.js

@@ -0,0 +1,274 @@
+const { execSync } = require("child_process");
+const os = require("os");
+const fs = require("fs");
+const path = require("path");
+
+const EVENT_CONFIG = {
+  Stop: {
+    title: "Claude Code 完成",
+    message: "Agent 已完成响应",
+    sound: "Glass",
+  },
+  TaskCompleted: {
+    title: "任务完成",
+    message: "任务已完成",
+    sound: "Hero",
+  },
+  Notification: {
+    title: "Claude Code 通知",
+    message: "需要你的注意",
+    sound: "Ping",
+  },
+  PostToolUseFailure: {
+    title: "工具执行失败",
+    message: "工具执行出错",
+    sound: "Basso",
+  },
+  SubagentStop: {
+    title: "子代理完成",
+    message: "子代理已完成任务",
+    sound: "Purr",
+  },
+  StopFailure: {
+    title: "Claude Code 错误",
+    message: "Claude Code 遇到错误中断",
+    sound: "Sosumi",
+  },
+};
+
+const ERROR_TYPE_LABELS = {
+  rate_limit: "请求频率限制",
+  authentication_failed: "认证失败",
+  billing_error: "账单/额度问题",
+  server_error: "服务器错误",
+  max_output_tokens: "输出超出 token 限制",
+  invalid_request: "无效请求",
+  unknown: "未知错误",
+};
+
+/**
+ * 从 hook 输入中提取有用信息
+ */
+function extractContext(hookInput) {
+  const ctx = {};
+
+  // 项目目录
+  ctx.project = path.basename(process.cwd());
+
+  // 任务主题 (TaskCompleted 事件)
+  if (hookInput.task_subject) {
+    ctx.taskSubject = hookInput.task_subject;
+  }
+
+  // 工具名称 (PostToolUseFailure 事件)
+  if (hookInput.tool_name) {
+    ctx.toolName = hookInput.tool_name;
+  }
+
+  // 错误类型 (StopFailure 事件)
+  if (hookInput.error_type) {
+    ctx.errorType = hookInput.error_type;
+  }
+
+  // 错误消息 (StopFailure 事件)
+  if (hookInput.error_message) {
+    ctx.errorMessage = hookInput.error_message;
+  }
+
+  // 停止原因 (Stop 事件)
+  if (hookInput.stop_reason) {
+    ctx.stopReason = hookInput.stop_reason;
+  }
+
+  // 尝试从 transcript 提取最后的 assistant 消息
+  if (hookInput.transcript_path && fs.existsSync(hookInput.transcript_path)) {
+    try {
+      const lines = fs
+        .readFileSync(hookInput.transcript_path, "utf-8")
+        .split("\n")
+        .filter(Boolean)
+        .slice(-20);
+
+      for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+          const entry = JSON.parse(lines[i]);
+          if (
+            entry?.message?.role === "assistant" &&
+            entry?.message?.content?.[0]?.text
+          ) {
+            ctx.lastMessage = entry.message.content[0].text
+              .replace(/\n/g, " ")
+              .slice(0, 100);
+            break;
+          }
+        } catch {
+          continue;
+        }
+      }
+    } catch {
+      // 读取失败，忽略
+    }
+  }
+
+  return ctx;
+}
+
+/**
+ * 构建通知标题和消息
+ */
+function buildNotification({ event, title, message, hookInput }) {
+  const config = EVENT_CONFIG[event] || EVENT_CONFIG.Stop;
+  const ctx = extractContext(hookInput || {});
+
+  let finalTitle = title || `${config.title} (${ctx.project})`;
+  let finalMessage = message;
+
+  if (!finalMessage) {
+    if (event === "StopFailure" && ctx.errorType) {
+      const label = ERROR_TYPE_LABELS[ctx.errorType] || ctx.errorType;
+      finalTitle = `${config.title}: ${label} (${ctx.project})`;
+      finalMessage = ctx.errorMessage || config.message;
+    } else if (event === "Stop" && ctx.stopReason === "max_tokens") {
+      finalTitle = `Claude Code 响应截断 (${ctx.project})`;
+      finalMessage = "响应达到最大 token 限制被截断";
+    } else if (event === "TaskCompleted" && ctx.taskSubject) {
+      finalMessage = ctx.taskSubject;
+    } else if (event === "PostToolUseFailure" && ctx.toolName) {
+      finalMessage = `工具 ${ctx.toolName} 执行失败`;
+    } else if (ctx.lastMessage) {
+      finalMessage = ctx.lastMessage;
+    } else {
+      finalMessage = config.message;
+    }
+  }
+
+  return { title: finalTitle, message: finalMessage, sound: config.sound };
+}
+
+/**
+ * 检测命令是否存在
+ */
+function commandExists(cmd) {
+  try {
+    execSync(
+      os.platform() === "win32" ? `where ${cmd}` : `command -v ${cmd}`,
+      { stdio: "ignore" }
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 发送系统桌面通知
+ */
+async function sendNotification(options = {}) {
+  const {
+    event = "Stop",
+    title: customTitle,
+    message: customMessage,
+    sound: customSound,
+    dryRun = false,
+    hookInput = {},
+  } = options;
+
+  const {
+    title,
+    message,
+    sound: defaultSound,
+  } = buildNotification({
+    event,
+    title: customTitle,
+    message: customMessage,
+    hookInput,
+  });
+  const sound = customSound || defaultSound;
+
+  const platform = os.platform();
+  let method = "unknown";
+  let command = "";
+  let args = [];
+
+  if (platform === "darwin") {
+    // macOS
+    if (commandExists("terminal-notifier")) {
+      method = "terminal-notifier";
+      command = "terminal-notifier";
+      args = [
+        "-title",
+        title,
+        "-message",
+        message,
+        "-sound",
+        sound,
+        "-group",
+        `claude-code-${extractContext(hookInput).project}`,
+      ];
+    } else {
+      method = "osascript";
+      command = "osascript";
+      const escaped = message.replace(/"/g, '\\"');
+      const escapedTitle = title.replace(/"/g, '\\"');
+      args = [
+        "-e",
+        `display notification "${escaped}" with title "${escapedTitle}" sound name "${sound}"`,
+      ];
+    }
+  } else if (platform === "linux") {
+    method = "notify-send";
+    command = "notify-send";
+    args = [title, message, "--urgency=normal", "--expire-time=5000"];
+    if (!commandExists("notify-send")) {
+      const result = {
+        sent: false,
+        method: "none",
+        error:
+          "notify-send 未安装。请运行: sudo apt-get install libnotify-bin",
+      };
+      if (dryRun) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(result.error);
+      }
+      return result;
+    }
+  } else if (platform === "win32") {
+    method = "powershell";
+    command = "powershell.exe";
+    const psScript = `
+      [void][System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms');
+      $n = New-Object System.Windows.Forms.NotifyIcon;
+      $n.Icon = [System.Drawing.SystemIcons]::Information;
+      $n.BalloonTipTitle = '${title.replace(/'/g, "''")}';
+      $n.BalloonTipText = '${message.replace(/'/g, "''")}';
+      $n.Visible = $true;
+      $n.ShowBalloonTip(5000);
+      Start-Sleep -Seconds 6;
+      $n.Dispose();
+    `.replace(/\n/g, " ");
+    args = ["-NoProfile", "-Command", psScript];
+  }
+
+  const result = { sent: !dryRun, method, command, args };
+
+  if (dryRun) {
+    result.sent = false;
+    console.log(JSON.stringify(result, null, 2));
+    return result;
+  }
+
+  try {
+    if (command) {
+      const { execFileSync } = require("child_process");
+      execFileSync(command, args, { stdio: "ignore", timeout: 5000 });
+    }
+  } catch (err) {
+    result.sent = false;
+    result.error = err.message;
+  }
+
+  return result;
+}
+
+module.exports = { sendNotification, EVENT_CONFIG };

package/src/setup.js

@@ -0,0 +1,260 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const PKG_NAME = "claude-hook-notify";
+
+// ANSI colors
+const c = {
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+};
+
+/**
+ * 生成 hooks 配置
+ */
+function generateHooksConfig(events) {
+  const hooks = {};
+  for (const event of events) {
+    hooks[event] = [
+      {
+        matcher: "",
+        hooks: [
+          {
+            type: "command",
+            command: `npx --yes ${PKG_NAME}@latest notify --event ${event}`,
+            timeout: 10,
+          },
+        ],
+      },
+    ];
+  }
+  return hooks;
+}
+
+/**
+ * 获取配置文件路径
+ */
+function getSettingsPath(scope) {
+  if (scope === "local") {
+    return path.join(process.cwd(), ".claude", "settings.json");
+  }
+  return path.join(os.homedir(), ".claude", "settings.json");
+}
+
+/**
+ * 安全读取 JSON 文件
+ */
+function readJSON(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    }
+  } catch {
+    // 文件损坏或不可读
+  }
+  return {};
+}
+
+/**
+ * 安全写入 JSON 文件
+ */
+function writeJSON(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * 检查平台依赖
+ */
+function checkDependencies() {
+  const platform = os.platform();
+  const warnings = [];
+
+  if (platform === "linux") {
+    try {
+      require("child_process").execSync("command -v notify-send", {
+        stdio: "ignore",
+      });
+    } catch {
+      warnings.push(
+        `${c.yellow("⚠")}  未检测到 notify-send，请安装：${c.cyan("sudo apt-get install libnotify-bin")}`
+      );
+    }
+  }
+
+  if (platform === "darwin") {
+    try {
+      require("child_process").execSync("command -v terminal-notifier", {
+        stdio: "ignore",
+      });
+      console.log(
+        `${c.green("✓")}  检测到 terminal-notifier（增强通知体验）`
+      );
+    } catch {
+      console.log(
+        `${c.dim("ℹ")}  可选：${c.cyan("brew install terminal-notifier")} 获得更好的通知体验`
+      );
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * 安装 hooks 配置
+ */
+async function setup({ scope = "global", events = ["Stop", "TaskCompleted", "Notification", "StopFailure"] }) {
+  const settingsPath = getSettingsPath(scope);
+  const scopeLabel = scope === "global" ? "全局" : "项目";
+
+  console.log();
+  console.log(
+    `  ${c.bold("🔔 Claude Code Notify — 安装向导")}`
+  );
+  console.log();
+
+  // 检查依赖
+  const warnings = checkDependencies();
+  warnings.forEach((w) => console.log(`  ${w}`));
+
+  // 读取现有配置
+  const settings = readJSON(settingsPath);
+  const existingHooks = settings.hooks || {};
+
+  // 检查是否已安装
+  const alreadyInstalled = events.some(
+    (event) =>
+      existingHooks[event]?.some((h) =>
+        h.hooks?.some((hh) => hh.command?.includes(PKG_NAME))
+      )
+  );
+
+  if (alreadyInstalled) {
+    console.log(
+      `  ${c.yellow("⚠")}  检测到已有 ${PKG_NAME} 的 hook 配置`
+    );
+    console.log(`  ${c.dim("   将会覆盖现有的通知 hook 配置")}`);
+    console.log();
+  }
+
+  // 生成新的 hooks 配置
+  const newHooks = generateHooksConfig(events);
+
+  // 合并配置（只覆盖 claude-hook-notify 相关的 hook，保留其他 hook）
+  for (const [event, hookConfigs] of Object.entries(newHooks)) {
+    if (existingHooks[event]) {
+      // 移除旧的 claude-hook-notify hook，保留其他
+      existingHooks[event] = existingHooks[event].filter(
+        (h) => !h.hooks?.some((hh) => hh.command?.includes(PKG_NAME))
+      );
+      // 追加新的
+      existingHooks[event].push(...hookConfigs);
+    } else {
+      existingHooks[event] = hookConfigs;
+    }
+  }
+
+  settings.hooks = existingHooks;
+
+  // 写入配置
+  writeJSON(settingsPath, settings);
+
+  // 输出结果
+  console.log(
+    `  ${c.green("✓")}  已写入${scopeLabel}配置: ${c.cyan(settingsPath)}`
+  );
+  console.log();
+  console.log(`  ${c.bold("已注册的事件:")}`);
+  for (const event of events) {
+    const labels = {
+      Stop: "Agent 完成响应时通知",
+      TaskCompleted: "子任务完成时通知",
+      Notification: "需要用户注意时通知",
+      PostToolUseFailure: "工具执行失败时通知",
+      SubagentStop: "子代理完成时通知",
+      StopFailure: "API 错误导致中断时通知",
+    };
+    console.log(
+      `     ${c.green("•")} ${c.bold(event)} — ${labels[event] || "自定义事件"}`
+    );
+  }
+  console.log();
+  console.log(
+    `  ${c.dim("重启 Claude Code 后生效。")}`
+  );
+  console.log(
+    `  ${c.dim(`卸载: npx ${PKG_NAME} uninstall${scope === "local" ? " --local" : ""}`)}`
+  );
+  console.log();
+}
+
+/**
+ * 卸载 hooks 配置
+ */
+async function uninstall({ scope = "global" }) {
+  const settingsPath = getSettingsPath(scope);
+  const scopeLabel = scope === "global" ? "全局" : "项目";
+
+  console.log();
+  console.log(`  ${c.bold("🔔 Claude Code Notify — 卸载")}`);
+  console.log();
+
+  if (!fs.existsSync(settingsPath)) {
+    console.log(`  ${c.yellow("⚠")}  未找到配置文件: ${settingsPath}`);
+    console.log();
+    return;
+  }
+
+  const settings = readJSON(settingsPath);
+  if (!settings.hooks) {
+    console.log(`  ${c.yellow("⚠")}  配置中没有 hooks`);
+    console.log();
+    return;
+  }
+
+  let removed = 0;
+
+  for (const [event, hookConfigs] of Object.entries(settings.hooks)) {
+    const before = hookConfigs.length;
+    settings.hooks[event] = hookConfigs.filter(
+      (h) => !h.hooks?.some((hh) => hh.command?.includes(PKG_NAME))
+    );
+    removed += before - settings.hooks[event].length;
+
+    // 清理空数组
+    if (settings.hooks[event].length === 0) {
+      delete settings.hooks[event];
+    }
+  }
+
+  // 清理空 hooks 对象
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  writeJSON(settingsPath, settings);
+
+  if (removed > 0) {
+    console.log(
+      `  ${c.green("✓")}  已从${scopeLabel}配置中移除 ${removed} 个通知 hook`
+    );
+  } else {
+    console.log(
+      `  ${c.yellow("ℹ")}  未找到 ${PKG_NAME} 相关的 hook 配置`
+    );
+  }
+  console.log(
+    `  ${c.dim("配置文件: " + settingsPath)}`
+  );
+  console.log();
+}
+
+module.exports = { setup, uninstall };