claude-notify-hub 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claude Notify Hub Contributors
+
+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,191 @@
+# Claude Code Notify Hub
+
+<div align="center">
+
+Get notified instantly when Claude Code needs you
+
+[中文文档](./README.zh-CN.md) | English
+
+[![npm version](https://img.shields.io/npm/v/claude-notify-hub.svg)](https://www.npmjs.com/package/claude-notify-hub)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+## What is this?
+
+Claude Code Notify Hub is a notification system that alerts you instantly when Claude Code needs your attention.
+
+**Use Cases:**
+- 🔔 Claude encounters an issue and needs your help
+- ✅ Claude completes the task you assigned
+- ⚠️ An error occurs during execution
+
+**Supported Notification Methods:**
+- 🗣️ **Voice Notifications** - Desktop alerts + text-to-speech (macOS/Windows/Linux)
+- 📧 **Email Notifications** - Send to your email (Gmail, Outlook, QQ Mail, etc.)
+
+## Quick Start
+
+### Step 1: Installation
+
+```bash
+npm install -g claude-notify-hub
+```
+
+### Step 2: Configuration
+
+```bash
+claude-notify init
+```
+
+Follow the prompts:
+
+1. **Select notification methods** (you can choose both):
+   - Voice notifications
+   - Email notifications
+
+2. **If you selected Voice notifications**:
+   - System will auto-detect your OS
+   - Choose whether to customize voice messages (optional)
+
+3. **If you selected Email notifications**:
+   - Select **587 (STARTTLS - Recommended for Gmail)**
+   - Enter your email address
+   - Enter password (Gmail requires app-specific password, see below)
+
+### Step 3: Test
+
+```bash
+# Test all notifications
+claude-notify test
+
+# Or test individually
+claude-notify test --voice
+claude-notify test --email
+
+# Test all four notification types (hear different sounds)
+claude-notify test --voice --all-types
+```
+
+**`--all-types` option:**
+
+This option tests all four notification types sequentially with 1.5 second intervals:
+
+1. 🔔 **intervention** (needs help) → Ping sound (clear chime)
+2. ✅ **complete** (task done) → Glass sound (crisp glass)
+3. ⚠️ **error** (error occurred) → Basso sound (deep warning)
+4. 🎉 **subagent_complete** (subtask done) → Glass sound (crisp glass)
+
+### Step 4: Start Using
+
+Once configured, **you don't need to do anything**!
+
+When Claude Code runs:
+- Needs your help → Auto notification
+- Task completed → Auto notification
+- Error occurs → Auto notification
+
+## Gmail Configuration
+
+**Important: Gmail requires an app-specific password, not your regular login password!**
+
+### Get Gmail App-Specific Password:
+
+1. Go to [Google Account Settings](https://myaccount.google.com/)
+2. Click "Security"
+3. Enable "2-Step Verification" (if not already enabled)
+4. Find "App passwords" under "2-Step Verification"
+5. Select "Mail" and your device
+6. Copy the generated 16-character password
+
+### When configuring, select:
+
+```
+? Select SMTP port and security:
+❯ 587 (STARTTLS - Recommended for Gmail)  ← Select this!
+  465 (SSL/TLS)
+  25 (No encryption - Not recommended)
+```
+
+## Other Email Services
+
+### QQ Mail
+
+- Login to QQ Mail → Settings → Account → Enable SMTP service
+- Get authorization code (not your QQ password)
+- Select `587 (STARTTLS)` when configuring
+
+### Outlook
+
+- Use your Outlook password directly
+- Select `587 (STARTTLS)` when configuring
+
+## Common Commands
+
+```bash
+# Reconfigure
+claude-notify config
+
+# Temporarily disable notifications
+claude-notify disable
+
+# Re-enable notifications
+claude-notify enable
+
+# Test notifications
+claude-notify test
+```
+
+## Configuration File
+
+Manual configuration if needed: `~/.config/claude-notify/config.json`
+
+## Troubleshooting
+
+### Voice notifications not working?
+
+**Linux users** need to install TTS tools first:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install espeak
+
+# Or
+sudo apt-get install festival
+```
+
+### Email sending fails?
+
+1. Confirm you're using **app-specific password** (not login password)
+2. Confirm you selected the correct port (587 for Gmail)
+3. Check network connection
+
+### How to temporarily disable notifications?
+
+```bash
+claude-notify disable
+```
+
+Re-enable when needed:
+
+```bash
+claude-notify enable
+```
+
+## Feedback
+
+Have issues? [Submit an Issue](https://github.com/knightnemo/claude-notify-hub/issues)
+
+## License
+
+MIT License
+
+---
+
+<div align="center">
+
+If this tool helps you, please give it a ⭐️
+
+Made with ❤️ for Claude Code users
+
+</div>

package/README.zh-CN.md

@@ -0,0 +1,191 @@
+# Claude Code Notify Hub
+
+<div align="center">
+
+让 Claude Code 在需要你时第一时间通知你
+
+[English](./README.md) | 简体中文
+
+[![npm version](https://img.shields.io/npm/v/claude-notify-hub.svg)](https://www.npmjs.com/package/claude-notify-hub)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+## 这是什么？
+
+Claude Code Notify Hub 是一个通知系统，让你在 Claude Code 需要你的时候能立即收到提醒。
+
+**适用场景：**
+- 🔔 Claude 遇到问题需要你的帮助
+- ✅ Claude 完成了你交给它的任务
+- ⚠️ 执行过程中发生错误
+
+**支持的通知方式：**
+- 🗣️ **语音通知** - 电脑弹窗 + 语音播报（支持 macOS/Windows/Linux）
+- 📧 **邮件通知** - 发送到你的邮箱（支持 Gmail、Outlook、QQ 邮箱等）
+
+## 你需要做什么？
+
+### 第一步：安装
+
+```bash
+npm install -g claude-notify-hub
+```
+
+### 第二步：配置
+
+```bash
+claude-notify init
+```
+
+跟着提示操作即可。你需要：
+
+1. **选择通知方式**（可以都选）：
+   - 语音通知
+   - 邮件通知
+
+2. **如果选了语音通知**：
+   - 系统会自动检测你的操作系统
+   - 选择是否自定义语音内容（可选，默认即可）
+
+3. **如果选了邮件通知**：
+   - 选择 **587 (STARTTLS - Recommended for Gmail)**
+   - 输入你的邮箱地址
+   - 输入密码（Gmail 需要使用应用专用密码，见下方说明）
+
+### 第三步：测试
+
+```bash
+# 测试所有通知
+claude-notify test
+
+# 或者单独测试
+claude-notify test --voice
+claude-notify test --email
+
+# 测试所有四种通知类型（听到不同的音效）
+claude-notify test --voice --all-types
+```
+
+**`--all-types` 选项说明：**
+
+使用这个选项可以依次测试所有四种通知类型，每种间隔 1.5 秒，你会听到不同的音效：
+
+1. 🔔 **intervention**（需要干预）→ Ping 音效（清脆的叮咚声）
+2. ✅ **complete**（任务完成）→ Glass 音效（轻快的玻璃声）
+3. ⚠️ **error**（发生错误）→ Basso 音效（低沉的警告声）
+4. 🎉 **subagent_complete**（子任务完成）→ Glass 音效（轻快的玻璃声）
+
+### 第四步：开始使用
+
+配置完成后，**不需要做任何事情**！
+
+当 Claude Code 运行时：
+- 需要你帮助时 → 自动发通知
+- 任务完成时 → 自动发通知
+- 出错时 → 自动发通知
+
+## Gmail 邮件配置说明
+
+**重要：Gmail 需要应用专用密码，不能直接用登录密码！**
+
+### 获取 Gmail 应用专用密码：
+
+1. 前往 [Google 账户设置](https://myaccount.google.com/)
+2. 点击「安全性」
+3. 开启「两步验证」（如果还没开启）
+4. 在「两步验证」下方找到「应用专用密码」
+5. 选择「邮件」和你的设备
+6. 复制生成的 16 位密码
+
+### 配置时选择：
+
+```
+? Select SMTP port and security:
+❯ 587 (STARTTLS - Recommended for Gmail)  ← 选这个！
+  465 (SSL/TLS)
+  25 (No encryption - Not recommended)
+```
+
+## 其他邮件服务
+
+### QQ 邮箱
+
+- 登录 QQ 邮箱 → 设置 → 账户 → 开启 SMTP 服务
+- 获取授权码（不是 QQ 密码）
+- 配置时选择 `587 (STARTTLS)`
+
+### Outlook
+
+- 直接使用你的 Outlook 密码
+- 配置时选择 `587 (STARTTLS)`
+
+## 常用命令
+
+```bash
+# 重新配置
+claude-notify config
+
+# 临时关闭通知
+claude-notify disable
+
+# 重新开启通知
+claude-notify enable
+
+# 测试通知
+claude-notify test
+```
+
+## 配置文件位置
+
+如果需要手动修改配置：`~/.config/claude-notify/config.json`
+
+## 常见问题
+
+### 语音通知不工作？
+
+**Linux 用户**需要先安装语音合成工具：
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install espeak
+
+# 或者
+sudo apt-get install festival
+```
+
+### 邮件发送失败？
+
+1. 确认你使用的是**应用专用密码**（不是登录密码）
+2. 确认选择了正确的端口（Gmail 用 587）
+3. 检查网络连接
+
+### 如何临时关闭通知？
+
+```bash
+claude-notify disable
+```
+
+需要时再开启：
+
+```bash
+claude-notify enable
+```
+
+## 问题反馈
+
+遇到问题？[提交 Issue](https://github.com/knightnemo/claude-notify-hub/issues)
+
+## 开源协议
+
+MIT License
+
+---
+
+<div align="center">
+
+如果这个工具对你有帮助，请给它一个 ⭐️
+
+Made with ❤️ for Claude Code users
+
+</div>

package/bin/claude-notify.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const packageJson = require('../package.json');
+const init = require('../src/cli/init');
+const test = require('../src/cli/test');
+const config = require('../src/cli/config');
+const send = require('../src/cli/send');
+
+program
+  .name('claude-notify')
+  .description('An out-of-the-box notification system for Claude Code')
+  .version(packageJson.version);
+
+program
+  .command('init')
+  .description('Initialize and configure Claude Code notifications')
+  .action(init);
+
+program
+  .command('test')
+  .description('Test all enabled notification methods')
+  .option('-v, --voice', 'Test voice notification only')
+  .option('-e, --email', 'Test email notification only')
+  .option('-a, --all-types', 'Test all notification types (intervention, complete, error, subagent_complete)')
+  .action(test);
+
+program
+  .command('config')
+  .description('Reconfigure notification settings')
+  .action(config);
+
+program
+  .command('send')
+  .description('Send a notification (used by Claude Code hooks)')
+  .requiredOption('-t, --type <type>', 'Notification type (intervention|complete|error|subagent_complete)')
+  .option('-n, --notifier <notifier>', 'Specific notifier to use (voice|email)')
+  .option('-m, --message <message>', 'Custom message')
+  .option('-c, --context <context>', 'Additional context (JSON string)')
+  .action(send);
+
+program
+  .command('enable')
+  .description('Enable Claude Code notifications')
+  .action(() => {
+    const configManager = require('../src/utils/config');
+    configManager.setEnabled(true);
+    console.log('✓ Claude Code notifications enabled');
+  });
+
+program
+  .command('disable')
+  .description('Disable Claude Code notifications')
+  .action(() => {
+    const configManager = require('../src/utils/config');
+    configManager.setEnabled(false);
+    console.log('✓ Claude Code notifications disabled');
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "claude-notify-hub",
+  "version": "1.0.0",
+  "description": "Get notified instantly when Claude Code needs you - Voice and Email notifications",
+  "main": "src/index.js",
+  "bin": {
+    "claude-notify": "./bin/claude-notify.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/claude-notify.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src/**/*.js bin/**/*.js",
+    "lint:fix": "eslint src/**/*.js bin/**/*.js --fix",
+    "format": "prettier --write \"**/*.{js,json,md}\"",
+    "prepare": "husky install"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "notification",
+    "voice",
+    "email",
+    "cli",
+    "hooks",
+    "desktop-notification",
+    "tts",
+    "text-to-speech",
+    "smtp",
+    "gmail",
+    "alerts"
+  ],
+  "author": "knightnemo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knightnemo/claude-notify-hub.git"
+  },
+  "bugs": {
+    "url": "https://github.com/knightnemo/claude-notify-hub/issues"
+  },
+  "homepage": "https://github.com/knightnemo/claude-notify-hub#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "boxen": "^5.1.2",
+    "chalk": "^4.1.2",
+    "cli-table3": "^0.6.3",
+    "commander": "^11.1.0",
+    "figures": "^3.2.0",
+    "inquirer": "^8.2.5",
+    "nodemailer": "^6.9.0",
+    "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "eslint": "^8.50.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-node": "^11.1.0",
+    "husky": "^8.0.3",
+    "jest": "^29.7.0",
+    "prettier": "^3.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli/config.js

@@ -0,0 +1,8 @@
+const init = require('./init');
+
+async function config() {
+  console.log('Reconfiguring Claude Code Notify...\n');
+  await init();
+}
+
+module.exports = config;