# agent-work-state-notification

**Repository Path**: ForgeRock/agent-work-state-notification

## Basic Information

- **Project Name**: agent-work-state-notification
- **Description**: 利用各AI Agent的hook能力通知Agent的工作状态，达到人机协同提高工作效率
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-05-16
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Claude Code Task Completion Notification

Claude Code 任务完成通知系统 - 支持 Hook Event 按类型控制通知

## 功能特性

- **Hook Event 过滤** - 按事件类型（stop/ask/plan/idle）独立控制通知
- **邮件通知** - SMTP 支持，安装时可配置，自动检测常见邮箱 SMTP
- **飞书通知** - 支持内网 MCP 服务器集成
- **声音通知** - macOS afplay / Windows PowerShell
- **弹出通知** - Windows Toast / macOS 通知中心
- **跨平台** - Linux / macOS / Windows 全支持

## 一键安装

### macOS / Linux

**方式一：交互式安装（推荐，可配置通知选项）**

```bash
# 下载安装脚本并执行
curl -fsSL https://gitee.com/ForgeRock/agent-work-state-notification/raw/master/install-remote.sh -o /tmp/install.sh && bash /tmp/install.sh
```

**方式二：非交互式安装（使用默认配置）**

```bash
# 快速安装（默认启用声音、弹窗、飞书通知，禁用邮件通知）
curl -fsSL https://gitee.com/ForgeRock/agent-work-state-notification/raw/master/install-remote.sh | bash
```

**卸载和更新**

```bash
# 卸载
curl -fsSL https://gitee.com/ForgeRock/agent-work-state-notification/raw/master/install-remote.sh | bash -s uninstall

# 更新
curl -fsSL https://gitee.com/ForgeRock/agent-work-state-notification/raw/master/install-remote.sh | bash -s update
```

### Windows PowerShell

**方式一：交互式安装（推荐，可配置通知选项）**

```powershell
# 下载安装脚本并执行
irm https://gitee.com/ForgeRock/agent-work-state-notification/raw/master/install-remote.ps1 -OutFile $env:TEMP\install.ps1; powershell -ExecutionPolicy Bypass -File $env:TEMP\install.ps1
```

**方式二：非交互式安装（使用默认配置）**

```powershell
# 快速安装（默认启用声音、弹窗、飞书通知，禁用邮件通知）
irm https://gitee.com/ForgeRock/agent-work-state-notification/raw/master/install-remote.ps1 | iex
```

**卸载和更新**

```powershell
# 卸载
irm https://gitee.com/ForgeRock/agent-work-state-notification/raw/master/install-remote.ps1 | iex; uninstall

# 更新
irm https://gitee.com/ForgeRock/agent-work-state-notification/raw/master/install-remote.ps1 | iex; update
```

## 安装时配置

安装过程中会交互式配置以下选项：

1. **声音通知** - 是否启用提示音
2. **飞书通知** - 是否启用飞书远程通知，输入员工邮箱（用于匹配飞书用户，与邮箱通知的个人邮箱区分）
3. **弹出通知** - 是否启用系统弹窗
4. **邮件通知** - 是否启用邮件通知，如启用则需填写：
   - 发件人邮箱（自动检测 SMTP 服务器地址和端口）
   - SMTP 授权码
   - 收件人邮箱

## 配置

安装后编辑配置文件：

### macOS / Linux
```bash
vim ~/.claude/hooks/claude-notification/config.json
```

### Windows
```powershell
notepad $env:USERPROFILE\.claude\hooks\claude-notification\config.json
```

### 配置结构

配置文件按 `channels`（通知渠道）和 `events`（触发事件）组织：

```json
{
  "channels": {
    "sound": {
      "enabled": true,
      "filePath": null
    },
    "feishu": {
      "enabled": false,
      "recipientEmail": "your-email@example.com"
    },
    "popup": {
      "enabled": true
    },
    "email": {
      "enabled": true,
      "smtp": {
        "host": "smtp.163.com",
        "port": 465
      },
      "sender": {
        "address": "yourname@163.com",
        "authCode": "your-smtp-auth-code"
      },
      "recipientEmail": "recipient@example.com",
      "subject": "Claude Code 任务完成通知"
    }
  },
  "events": {
    "ask": true,
    "plan": true,
    "idle": false,
    "stop": true
  }
}
```

### Hook Event 说明

| 事件 | 说明 | 默认 |
|------|------|------|
| `stop` | Claude 任务完成 | true |
| `ask` | 等待用户选择/输入 | true |
| `plan` | 方案生成等待审批 | true |
| `idle` | 空闲等待输入 | false |

## 测试

### macOS / Linux
```bash
# 测试通知功能
bash ~/.claude/hooks/claude-notification/debug.sh
```

### Windows PowerShell
```powershell
# 测试通知功能
powershell -ExecutionPolicy Bypass -File $env:USERPROFILE\.claude\hooks\claude-notification\debug.ps1
```

## 详细文档

- [配置说明](CONFIG.md)
- [调试指南](DEBUG.md)

## 文件结构

```
~/.claude/hooks/claude-notification/
├── config.json              # 用户配置
├── hook.sh / hook.cmd       # 主入口
├── notify.sh / notify.ps1   # 飞书通知
├── popup.sh / popup.ps1     # 弹出通知
├── email-notify.py          # 邮件通知
├── play-sound.sh            # 声音播放
├── notification.wav         # 声音文件（Windows）
└── notification.aiff        # 声音文件（macOS）
```

## 卸载

```bash
# macOS / Linux
curl -fsSL https://gitee.com/forwardxiang_admin/claude-notification-installer/raw/master/install-remote.sh | bash -s uninstall

# Windows PowerShell
irm https://gitee.com/forwardxiang_admin/claude-notification-installer/raw/master/install-remote.ps1 | iex; uninstall
```

## 仓库地址

- Gitee: https://gitee.com/ForgeRock/agent-work-state-notification

## 许可证

MIT License