cc-hook/README.md

cc-hook

🤗 Claude Code 钩子服务，将 Claude Code 事件转发至 Gotify 推送通知。

功能特性

• 实时通知：当 Claude Code 需要关注时，立即收到手机推送
• 多事件支持：Notification（权限请求、等待输入等）和 Stop（任务完成）
• 轻量部署：单个 Docker 容器，资源占用极低
• 灵活配置：通过环境变量自定义 Gotify 服务器和 Token

架构概览

graph LR
    A[Claude Code] -->|POST /hooks| B[cc-hook]
    B -->|POST /message| C[Gotify]
    C -->|推送通知| D[手机/客户端]

前置条件

• Docker 和 Docker Compose
• Claude Code 已安装
• Gotify 服务器（自建或公共）

快速开始

1. 克隆项目

git clone <your-repo-url> cc-hook
cd cc-hook

2. 配置环境变量

编辑 docker-compose.yml，修改以下配置：

environment:
  - GOTIFY_URL=http://your-gotify-server:port    # Gotify 服务器地址
  - GOTIFY_TOKEN=your-token-here                  # Gotify 应用 Token
  - PORT=:8082                                     # 服务监听端口（默认 8082）

3. 启动服务

docker-compose up -d

4. 配置 Claude Code

将以下内容添加到 ~/.claude/settings.json：

{
  "hooks": {
    "Notification": [
      {
        "type": "command",
        "command": "curl -s -X POST http://localhost:8082/hooks -H 'Content-Type: application/json' -d @-"
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "curl -s -X POST http://localhost:8082/hooks -H 'Content-Type: application/json' -d @-"
      }
    ]
  }
}

支持的事件

Notification 事件

Matcher	标题	优先级	说明
permission_prompt	需要权限	7	Claude 需要你批准一个操作
idle_prompt	等待输入	5	Claude 完成工作，等待下一步指令
auth_success	认证成功	3	身份验证完成
其他	通知	5	默认通知

Stop 事件

条件	标题	优先级	说明
正常完成	任务完成	5	Claude 完成了本轮回复
循环检测	循环停止	8	Stop hook 连续触发多次，已自动停止

配置说明

环境变量	默认值	说明
GOTIFY_URL	http://47.121.181.112:40266	Gotify 服务器地址
GOTIFY_TOKEN	AiousrPBE4Cn04C	Gotify 应用 Token
PORT	:8082	服务监听端口

API 端点

POST /hooks

接收 Claude Code Hook 事件并转发至 Gotify。

请求体示例：

{
  "session_id": "abc123",
  "cwd": "/home/user/project",
  "hook_event_name": "Notification",
  "matcher": "permission_prompt"
}

响应：

• 成功：{"status":"ok"}
• 忽略：{"status":"ignored"}
• 错误：HTTP 500

GET /health

健康检查端点。

响应：

{"status":"ok"}

本地开发

直接运行

# 安装依赖
go mod tidy

# 设置环境变量
export GOTIFY_URL=http://your-gotify-server:port
export GOTIFY_TOKEN=your-token

# 运行
go run .

测试

# 健康检查
curl http://localhost:8082/health

# 模拟 Notification 事件
curl -X POST http://localhost:8082/hooks \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"test","cwd":"/tmp","hook_event_name":"Notification","matcher":"permission_prompt"}'

# 模拟 Stop 事件
curl -X POST http://localhost:8082/hooks \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"test","cwd":"/tmp","hook_event_name":"Stop"}'

项目结构

cc-hook/
├── config.go           # 配置管理（环境变量读取）
├── gotify.go           # Gotify HTTP 客户端
├── handler.go          # Hook 事件处理器
├── main.go             # HTTP 服务入口
├── Dockerfile          # 多阶段 Docker 构建
├── docker-compose.yml  # Docker Compose 部署配置
└── go.mod              # Go 模块定义

扩展计划

• 数据库记录：将 Hook 事件写入数据库，便于复盘和分析
• 更多事件支持：Tool Use、Error 等事件类型
• 消息模板：自定义通知消息格式
• 多 Gotify 支持：同时推送到多个 Gotify 服务器

License

MIT