🔔 Claude Code Notifier

English Version

🔔 Claude Code Notifier

智能化的 Claude Code 通知系统 - 提供实时、多渠道的操作通知和智能限制功能

✨ 特性

🎯 核心功能

智能检测 - 自动检测权限操作和任务完成
全局生效 - 一次配置，所有项目自动启用
多渠道支持 - 支持 6+ 种主流通知渠道
美化通知 - 精美的卡片格式和分层设计
易于配置 - 简单的配置文件和安装脚本
安全可靠 - 支持签名验证和加密传输

🧠 智能功能

智能限流 - 防止通知轰炸，支持冷却时间和频率控制
消息分组 - 自动合并相似通知，避免重复打扰
操作门控 - 智能识别敏感操作，需要用户确认
自适应调节 - 根据使用模式自动优化通知策略

⚙️ 高级配置

事件开关 - 灵活的事件启用/禁用配置
自定义事件 - 支持用户自定义触发条件和通知内容
模板系统 - 统一的模板引擎，支持自定义样式
多渠道路由 - 不同事件可配置不同的通知渠道组合
统计监控 - 事件统计和通知效果分析
配置备份 - 支持配置备份和恢复功能

🆕 最新改进 (v0.0.8 - Stable)

🛠️ 代码质量与兼容性修复

🔧 Hooks API 适配 - 修复 installer.py 和 claude_hook.py 以适配新版 Claude Code Hooks API（PreToolUse、PostToolUse、Stop、Notification 等列表格式）
🛡️ 类型安全增强 - 修复类型检查问题，提升代码健壮性
✅ 测试用例更新 - 更新 14 个测试用例以匹配实际事件实现
🐛 异常处理优化 - 使用具体异常类型替代裸 except
🗑️ 代码清理 - 删除废弃的 ConfirmationRequiredEvent 类

✨ CLI Commands 模块优化

📦 CLI 模块重构 - 将 CLI 命令按功能拆分到独立模块（core、config、hooks、debug）
🔧 代码质量修复 - 配置缓存、权限比较、清屏方法等多项优化
🚀 CI/CD 友好 - 添加 --yes/-y 选项支持非交互式卸载

� 新版 Hooks API 支持

🎯 PreToolUse 钩子 - 工具使用前触发，支持敏感操作检测（Bash、Edit、Write、DeleteFile 等）
📊 PostToolUse 钩子 - 工具使用后触发，支持错误检测和结果记录
✅ Stop 钩子 - Claude 停止工作时触发，用于任务完成通知
🔔 Notification 钩子 - 处理权限请求（permission_prompt）和空闲提示（idle_prompt）
� 向后兼容 - 保留旧版 API 支持，通过命令行参数调用

🚀 PyPI版本Claude Code钩子自动配置（重大更新）

🎉 突破性功能：PyPI用户现在享受与Git用户相同的无缝体验！

✅ ⚡ 一键智能配置 - claude-notifier setup --auto 自动检测和配置所有功能
✅ 🔧 完整钩子管理 - 新增 hooks 命令组，提供安装/卸载/状态/验证功能
✅ 💡 智能环境检测 - 自动发现Claude Code安装，支持多种安装位置
✅ 📊 增强状态显示 - --status 现在包含完整的钩子系统状态
✅ 🛡️ 错误恢复机制 - 即使依赖缺失也能基本工作，提供优雅降级
✅ 🔄 双模式兼容 - 钩子系统支持PyPI和Git两种模式，智能切换

🔧 版本管理改进

✅ PEP 440 版本规范 - 采用 a/b/rc 预发行规范与稳定版并行策略
✅ CLI 版本提示 - 稳定版不显示预发行提示；预发行显示"版本类型: Alpha/Beta/RC"
✅ README 徽章 - 更新为 Stable 徽章
✅ CI/CD 工作流 - 使用 GitHub Actions 构建并发布稳定版到 PyPI；预发行通过仓库 Tag/Release 管理

📱 支持的通知渠道

渠道	状态	特性
🔔 钉钉机器人	✅	ActionCard + Markdown
🔗 Webhook	✅	HTTP 回调 + 多格式 + 多认证
🚀 飞书机器人	🚧 开发中	富文本 + 交互卡片
💼 企业微信机器人	🚧 开发中	Markdown + 图文消息
🤖 Telegram	🚧 开发中	Bot 消息推送
📮 邮箱	🚧 开发中	SMTP 邮件推送
📧 Server酱	🚧 开发中	微信推送

🚀 快速开始

方式一：PyPI 安装（推荐，适合普通用户）

# 安装最新稳定版
pip install claude-code-notifier
# 或安装指定版本
pip install claude-code-notifier==0.0.8
# 验证安装
claude-notifier --version
# 🚀 一键智能配置（新功能！）
claude-notifier setup --auto

🎉 新功能：PyPI版本现已支持Claude Code钩子自动配置！

安装后系统会自动：

📦 创建配置目录 ~/.claude-notifier/
⚙️ 生成默认配置文件
🔧 设置 CLI 命令
🔍 智能检测Claude Code并提示集成
⚡ 一键配置Claude Code钩子

适合人群：普通用户、快速体验、生产环境使用

方式二：Git 源码安装（适合开发者）

2.1 智能安装（推荐）

git clone https://github.com/kdush/Claude-Code-Notifier.git
cd Claude-Code-Notifier
./install.sh

✨ 新版智能安装系统特性：

🎯 智能模式选择 - 自动检测环境并推荐最佳安装方式
📦 三种安装模式 - PyPI/Git/混合，满足不同需求
🔄 自动更新机制 - 定时检查，一键更新
🔗 统一命令接口 - cn 命令自动路由到正确执行方式
📊 版本管理 - 统一的版本信息和升级路径

快速配置：

# 安装后运行配置向导
python3 scripts/quick_setup.py

快速配置脚本将引导您：

📱 配置通知渠道（钉钉、飞书、Telegram、邮箱等）
🎯 选择要启用的事件类型
🔧 添加自定义事件
⚙️ 设置高级选项（频率限制、静默时间等）
🧪 测试通知配置

2.2 手动配置

git clone https://github.com/kdush/Claude-Code-Notifier.git
cd Claude-Code-Notifier
chmod +x install.sh
./install.sh
# 复制配置模板
cp config/enhanced_config.yaml.template config/config.yaml
# 编辑配置文件
vim config/config.yaml

适合人群：开发者、贡献者、需要自定义功能、测试最新特性

安装方式对比

特性	PyPI 安装	Git 源码安装
🎯 目标用户	普通用户	开发者
⚡ 安装速度	快速	较慢
🔄 更新方式	`pip install --upgrade`	`git pull` + 重新安装
🧪 测试版本	稳定版本	最新开发版
🛠️ 自定义能力	基础配置	完全自定义
📦 依赖管理	自动处理	手动管理
🔗 Claude Code 集成	✅ 自动配置钩子	✅ 自动设置 Hook
📁 目录结构	标准 Python 包	完整项目结构
🚀 一键配置	✅ `setup` 命令	✅ 安装脚本

配置和测试

PyPI 用户配置

# 🚀 一键智能配置（推荐）
claude-notifier setup --auto
# 🔧 分步配置
claude-notifier setup # 交互式配置
claude-notifier hooks install # 配置Claude Code钩子
claude-notifier test# 测试通知
claude-notifier --status # 查看完整状态# 📊 钩子管理
claude-notifier hooks status # 查看钩子状态
claude-notifier hooks verify # 验证钩子配置
claude-notifier hooks uninstall # 卸载钩子（如需要）

统一命令接口

🔗 无论使用哪种安装方式，都可以使用统一的 cn 命令：

# 智能命令路由 - 自动选择正确的执行方式
cn init # 初始化配置
cn test# 测试通知
cn status # 查看状态
cn --help # 查看帮助

更新管理

🔄 智能更新系统：

# 检查更新
python3 scripts/smart_update.py --check
# 执行更新
python3 scripts/smart_update.py --update
# 启用自动更新
python3 scripts/smart_update.py --enable-auto
# 查看更新状态
python3 scripts/smart_update.py --status

自动更新特性：

✅ 自动检测安装类型（PyPI/Git）
✅ 智能版本比较和更新
✅ 定时检查（每天一次）
✅ 配置备份和迁移
✅ 更新日志记录

Git 源码用户测试

./scripts/test.sh
# 测试特定渠道
./scripts/test.sh --channel dingtalk

📋 使用场景

🔐 权限确认通知

当 Claude Code 检测到敏感操作时：

自动暂停执行
发送权限确认通知
在终端中等待用户确认

✅ 任务完成通知

当 Claude Code 完成所有任务时：

发送完成庆祝通知
显示执行摘要
提供操作建议

📊 通知效果预览

钉钉机器人通知

权限确认 (ActionCard 格式)

🔐 Claude Code 权限检测
---
⚠️ 检测到敏感操作
> Claude Code 已自动暂停执行
---
📂 项目: my-awesome-project
⚡ 操作: sudo systemctl restart nginx
💡 请在终端中确认操作
[📱 查看终端] 按钮

任务完成 (Markdown 格式)

✅ Claude Code 任务完成
🎉 工作完成，可以休息了！
📂 项目: my-awesome-project 📋 状态: 代码重构任务已完成
⏰ 时间: 2025-08-20 15:30:20
☕ 建议您休息一下或检查结果

⚙️ 配置文件

配置文件位于 ~/.claude-notifier/config.yaml：

# 通知渠道配置channels:
dingtalk:
enabled: truewebhook: "https://oapi.dingtalk.com/robot/send?access_token=..."secret: "SEC..."feishu:
enabled: truewebhook: "https://open.feishu.cn/open-apis/bot/v2/hook/..."# 通知设置notifications:
permission:
enabled: truechannels: ["dingtalk", "feishu"]completion:
enabled: truechannels: ["dingtalk"]delay: 3# 检测规则detection:
permission_patterns:
- "sudo"
- "rm -"
- "chmod"
- "git push"
- "npm publish"
- "docker"
- "kubectl"

🛠️ 开发指南

添加新的通知渠道

在 src/claude_notifier/core/channels/ 创建新的渠道文件
实现 BaseChannel 接口和必需的类属性
在 src/claude_notifier/core/channels/__init__.py 中注册渠道
在配置文件中添加渠道配置模板
更新文档和测试

详细开发指南请参考 docs/development.md

自定义检测规则

编辑 ~/.claude-notifier/config.yaml 中的 detection 部分。

🔧 CLI 使用示例

# 发送通知
claude-notifier send "Hello World!"# 测试配置
claude-notifier test# 查看状态
claude-notifier status --intelligence
# 配置管理## 📦 版本规范与预发行流程
- **版本规范（PEP 440）**
- 预发行：`aN`（Alpha）、`bN`（Beta）、`rcN`（候选），如：`0.0.3a1`、`0.0.3b4`、`0.0.3rc1`
- 稳定版：去掉预发行后缀，如：`0.0.3`
- 版本源文件：`src/claude_notifier/__version__.py`
- **预发行策略**
- 使用 Git 标签发布预发行（如 `v0.0.3b4`），创建仓库 Release 并附带变更说明
- CLI `--version` 显示“版本类型: Alpha/Beta/RC”和预发行提示
- 如需分发，可手动将预发行上传至 PyPI（可选）
- **稳定版发布（默认）**
- `vX.Y.Z` 标签触发 GitHub Actions 构建（sdist + wheel）并发布到 PyPI
- 同步更新 `CHANGELOG.md` 与文档
详见：[开发文档（版本规范与预发行流程章节）](docs/development.md)
## 📚 文档
- [快速开始](docs/quickstart.md) - 安装和基础配置
- [配置指南](docs/configuration.md) - 详细配置说明
- [渠道配置](docs/channels.md) - 各渠道具体配置
- [高级使用](docs/advanced-usage.md) - 自定义事件和ccusage集成
- [开发文档](docs/development.md) - 架构和开发指南
## 📊 使用统计与分析
本项目集成了 [ccusage](https://github.com/ryoppippi/ccusage) 来分析 Claude Code 的 token 使用和成本统计：
```bash# 分析本地使用数据npx ccusagebunx ccusage# 查看月度统计ccusage --monthly# 生成使用报告ccusage --output usage-report.json

ccusage 功能：

📈 令牌使用分析 - 详细的 token 消费统计
💰 成本追踪 - 不同 Claude 模型的费用分解
📅 时间段报告 - 日/月/会话级别的使用分析
⚡ 实时监控 - 5小时计费窗口监控
📊 离线分析 - 基于本地 JSONL 文件的数据处理

感谢 @ryoppippi 开发的这个优秀工具！

💻 平台兼容性

测试环境

✅ macOS 15 - 完全测试和支持
🚧 Windows/Linux - 理论支持，但尚未充分测试

跨平台兼容性

本项目在设计时考虑了跨平台兼容性：

🪟 Windows支持 - 钩子安装器已针对Windows命令行和路径处理进行优化
🐧 Linux支持 - 使用标准Python和shell命令，应该可以正常工作
🔧 自动平台检测 - 代码中包含os.name和平台特定的处理逻辑

欢迎贡献

🙏 诚邀其他平台用户测试和完善：

如果您在Windows或Linux上使用，欢迎反馈使用体验
发现问题请提交Issue，我们会积极解决
欢迎提交平台特定的改进和修复PR

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

Apache License

⭐ Star History

💡 让 Claude Code 更智能，让开发更高效！

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
config		config
docs		docs
examples		examples
scripts		scripts
src		src
templates		templates
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE.txt		LICENSE.txt
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
README_en.md		README_en.md
RELEASE_v0.0.6.md		RELEASE_v0.0.6.md
demo.sh		demo.sh
install.sh		install.sh
package.json		package.json
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py
status.json		status.json
upgrade.sh		upgrade.sh

Latest commit

History

Folders and files

Repository files navigation

🔔 Claude Code Notifier

✨ 特性

🎯 核心功能

🧠 智能功能

⚙️ 高级配置

🆕 最新改进 (v0.0.8 - Stable)

🛠️ 代码质量与兼容性修复

✨ CLI Commands 模块优化

� 新版 Hooks API 支持

🚀 PyPI版本Claude Code钩子自动配置（重大更新）

🔧 版本管理改进

📱 支持的通知渠道

🚀 快速开始

方式一：PyPI 安装（推荐，适合普通用户）

方式二：Git 源码安装（适合开发者）

2.1 智能安装（推荐）

2.2 手动配置

安装方式对比

配置和测试

PyPI 用户配置

统一命令接口

更新管理

Git 源码用户测试

📋 使用场景

🔐 权限确认通知

✅ 任务完成通知

📊 通知效果预览

钉钉机器人通知

⚙️ 配置文件

🛠️ 开发指南

添加新的通知渠道

自定义检测规则

🔧 CLI 使用示例

💻 平台兼容性

测试环境

跨平台兼容性

欢迎贡献

🤝 贡献

📄 许可证

⭐ Star History

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages