@lonely9206/cc-hooks

Claude Code hooks 工具，自动记录 prompts 和代码变更，帮助团队了解 AI 辅助编程情况。

• 记录内容：prompt 使用情况、文件变更、代码行数增删
• 数据用途：仅用于团队内部统计，不对外公开
• 隐私说明：不监控隐私，只统计代码产出；本地缓存仅用于排错和失败重试

安装要求

• Node.js >= 16
• Claude Code 已安装

全局安装

推荐全局安装，避免污染项目目录：

npm install -g @lonely9206/cc-hooks

全局初始化

cc-hooks init

初始化会写入：

• 用户配置：~/.cc-hooks/config
• 全局 hooks：~/.claude/settings.json

初始化一次后，重启 Claude Code，所有 git 项目都会自动生效。

什么情况下会触发 hook 记录？

前提：全局运行一次 cc-hooks init 后，所有 git 项目都会自动记录。

• UserPromptSubmit：你按回车发送 prompt 时触发，记录 prompt 文本，并创建本地当前文件快照基线。
• PostToolBatch：记录本轮写工具候选文件集合，不向数据库提交数据。
• Stop：Claude 本轮回复结束时触发，只对本轮候选文件做 baseline/final 本地快照对比，并一次性记录真实变化和增删行数。

说明：

• 只在 git 项目内记录，非 git 目录会跳过
• 变更检测基于本地快照（~/.cc-hooks/snapshots）完成；snapshot 不上传数据库
• API 仅接收 prompt 日志和 Stop 阶段最终一次 files_changed 变更统计
• PostToolBatch 候选路径来自 Edit、Write、MultiEdit、NotebookEdit；Bash 产生的文件不会被计入候选路径模式
• 行数是快照估算：新文件按整文件行数计，修改文件按总行数差计，不等同于 git diff
• 首次扫描大量已有文件时只建立基线，避免把旧文件误报为新增
• 只记录最近 1 小时内修改/创建/删除的文件，减少外部操作噪音
• 会过滤 .gitignore 命中的文件、构建产物、依赖目录、缓存目录等
• 当前统计代码类文件：.py、.js、.ts、.tsx、.jsx、.vue、.java、.go、.rb、.php、.c、.cpp、.cs、.html、.css、.scss、.hql

命令

• cc-hooks init：全局初始化 hooks（交互式设置用户名）
• cc-hooks doctor：检查安装、配置、hooks、API，并默认发送测试记录
• cc-hooks logs：查看今日当前项目本地 hook 记录
• cc-hooks logs all：查看今日所有项目本地 hook 记录
• cc-hooks update：检查并更新到最新版本
• cc-hooks user：查看当前用户
• cc-hooks set-user 名字：设置用户名
• cc-hooks uninstall：移除 hooks 配置
• cc-hooks prompt "text"：手动记录一条 prompt
• cc-hooks stop：汇总本轮文件变更
• cc-hooks changes：兼容检测文件变更
• cc-hooks changes --watch-dir <dir>：指定目录检测文件变更
• cc-hooks --version：查看版本

诊断

cc-hooks doctor

doctor 会检查 Node.js、Claude Code 版本、用户名配置、全局 hooks、API 可达性，并默认发送一条带真实机器版本信息的测试 prompt 和一次 changes 测试。不直接检查数据库，也不会自动修复配置。

本地日志与失败重试

查看今日 hook 记录：

cc-hooks logs
cc-hooks logs all

本地日志位置：

~/.cc-hooks/cache/hooks-YYYY-MM-DD.jsonl

当 API 临时不可用时，cc-hooks 会把待上报事件放入本地 outbox，后续执行 prompt 或 changes 时先尝试补发，避免短暂网络故障导致数据丢失。

hook 执行异常会输出详细日志文件路径；日志只用于本地排错，不影响主流程继续使用 Claude Code。

用户名

用户名优先级：用户填写 > git 作者 > 系统用户名。

存储在：

~/.cc-hooks/config

工作原理

1. 安装：npm install -g @lonely9206/cc-hooks
2. 初始化：cc-hooks init（全局运行一次，会提示输入用户名）
3. 重启 Claude Code
4. 使用：正常使用 Claude Code，hooks 自动记录
5. 排查：需要时运行 cc-hooks doctor 或 cc-hooks logs