cc-hook/README.md

# cc-hook

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

## 功能特性

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

## 架构概览

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

## 前置条件

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

## 快速开始

### 1. 克隆项目

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

### 2. 配置环境变量

复制 `.env.example` 并填写实际配置：

```bash
cp .env.example .env
```

编辑 `.env`：

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

### 3. 启动服务

```bash
docker-compose up -d
```

### 4. 配置 Claude Code

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

```json
{
  "hooks": {
    "Notification": [
      {
        "type": "command",
        "command": "curl -s -X POST http://47.121.181.112:8082/hooks -H 'Content-Type: application/json' -d @-"
      }
    ],
    "Stop": [
      {
        "type": "command",
        "command": "curl -s -X POST http://47.121.181.112: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` | 是 | Gotify 服务器地址 |
| `GOTIFY_TOKEN` | 是 | Gotify 应用 Token |
| `PORT` | 否 | 服务监听端口（默认 `:8082`） |

## API 端点

### POST /hooks

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

**请求体示例：**
```json
{
  "session_id": "abc123",
  "cwd": "/home/user/project",
  "hook_event_name": "Notification",
  "matcher": "permission_prompt"
}
```

**响应：**
- 成功：`{"status":"ok"}`
- 忽略：`{"status":"ignored"}`
- 错误：HTTP 500

### GET /health

健康检查端点。

**响应：**
```json
{"status":"ok"}
```

## 本地开发

### 直接运行

```bash
# 安装依赖
go mod tidy

# 复制并编辑配置
cp .env.example .env

# 运行（自动加载 .env）
go run .
```

### 测试

```bash
# 健康检查
curl http://47.121.181.112:8082/health

# 模拟 Notification 事件
curl -X POST http://47.121.181.112: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://47.121.181.112:8082/hooks \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"test","cwd":"/tmp","hook_event_name":"Stop"}'
```

## 项目结构

```
cc-hook/
├── .env.example        # 环境变量示例
├── .gitignore          # Git 忽略规则
├── 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