# Claude Code Monitor

监听 Claude Code 执行状态，在任务完成或需要用户输入时发送 Telegram 通知。

## 文件说明

| 文件 | 说明 |
|------|------|
| `claude_monitor.py` | Claude Code 状态监听脚本 |
| `notify_telegram.py` | Telegram 通知脚本 |

## 快速开始

### 1. 安装依赖

```bash
pip install watchdog python-dotenv
```

或使用 uv:

```bash
uv sync
```

### 2. 启动监控

```bash
# 监控最近活跃的项目
uv run python claude_monitor.py --json | uv run python notify_telegram.py

# 监控指定项目
uv run python claude_monitor.py --json -p ~/.claude/projects/-your-project | uv run python notify_telegram.py

# 列出所有可用项目
uv run python claude_monitor.py --list
```

### 3. 后台运行

```bash
nohup python claude_monitor.py --json | python notify_telegram.py > monitor.log 2>&1 &

# 查看日志
tail -f monitor.log

# 停止监控
pkill -f claude_monitor.py
```

## 通知类型

| 状态 | 说明 | 通知 Emoji |
|------|------|------------|
| `TASK_COMPLETE` | 任务执行完成 | ✅ |
| `USER_QUESTION` | Claude 需要用户输入 | ❓ |
| `PENDING_PERMISSION` | Claude 等待工具权限确认 | ⏳ |
| `ERROR_STOP` | 执行出错停止 | ❌ |

## 配置

### 环境变量

通知脚本支持通过环境变量覆盖默认配置：

```bash
# Telegram Bot 配置
export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"
export TELEGRAM_PROXY="http://127.0.0.1:7890"  # 可选

# 通知开关
export NOTIFY_ON_COMPLETE="true"   # 任务完成时通知
export NOTIFY_ON_USER_QUESTION="true"  # 需要输入时通知
export NOTIFY_ON_PENDING_PERMISSION="true"  # 等待权限确认时通知
export NOTIFY_ON_ERROR="true"      # 出错时通知
```

### 禁用特定通知

```bash
# 只在需要输入时通知
NOTIFY_ON_COMPLETE=false NOTIFY_ON_ERROR=false python claude_monitor.py --json | python notify_telegram.py
```

## 开机自启动

### macOS (launchd)

#### 方法一：使用 LaunchAgent（推荐）

1. 创建 plist 文件：

```bash
cat > ~/Library/LaunchAgents/com.user.claude-monitor.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.claude-monitor</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>cd /Users/xiaoming/code/codexspec/scripts/python && /usr/bin/python3 claude_monitor.py --json | /usr/bin/python3 notify_telegram.py</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/claude-monitor.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/claude-monitor.err</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>
EOF
```

2. 加载服务：

```bash
# 加载
launchctl load ~/Library/LaunchAgents/com.user.claude-monitor.plist

# 检查状态
launchctl list | grep claude-monitor

# 停止
launchctl unload ~/Library/LaunchAgents/com.user.claude-monitor.plist
```

#### 方法二：登录项脚本

1. 创建启动脚本：

```bash
cat > /Users/xiaoming/code/codexspec/scripts/python/start-monitor.sh << 'EOF'
#!/bin/bash
cd /Users/xiaoming/code/codexspec/scripts/python
nohup python3 claude_monitor.py --json | python3 notify_telegram.py > /tmp/claude-monitor.log 2>&1 &
EOF

chmod +x /Users/xiaoming/code/codexspec/scripts/python/start-monitor.sh
```

2. 添加到登录项：
   - 系统设置 → 通用 → 登录项与扩展
   - 点击 "+" 添加 `start-monitor.sh`

### Linux (systemd)

1. 创建服务文件：

```bash
sudo cat > /etc/systemd/system/claude-monitor.service << 'EOF'
[Unit]
Description=Claude Code Monitor with Telegram Notification
After=network.target

[Service]
Type=simple
User=xiaoming
WorkingDirectory=/Users/xiaoming/code/codexspec/scripts/python
ExecStart=/bin/bash -c 'python3 claude_monitor.py --json | python3 notify_telegram.py'
Restart=always
RestartSec=10
StandardOutput=append:/tmp/claude-monitor.log
StandardError=append:/tmp/claude-monitor.err

[Install]
WantedBy=multi-user.target
EOF
```

2. 启用服务：

```bash
# 重载配置
sudo systemctl daemon-reload

# 启用开机自启
sudo systemctl enable claude-monitor

# 启动服务
sudo systemctl start claude-monitor

# 查看状态
sudo systemctl status claude-monitor

# 查看日志
journalctl -u claude-monitor -f
```

### 使用 cron (通用)

```bash
# 编辑 crontab
crontab -e

# 添加以下行（开机后 1 分钟启动）
@reboot sleep 60 && cd /Users/xiaoming/code/codexspec/scripts/python && nohup python3 claude_monitor.py --json | python3 notify_telegram.py > /tmp/claude-monitor.log 2>&1 &
```

## 故障排查

### 检查脚本是否运行

```bash
ps aux | grep claude_monitor
```

### 查看日志

```bash
# 如果使用 nohup
tail -f monitor.log

# 如果使用 launchd (macOS)
tail -f /tmp/claude-monitor.log /tmp/claude-monitor.err

# 如果使用 systemd (Linux)
journalctl -u claude-monitor -f
```

### 测试 Telegram 通知

```bash
echo '{"session_id":"test123","status":"TASK_COMPLETE","stop_reason":"end_turn","output":"Test message"}' | python3 notify_telegram.py
```

### 检查网络代理

如果 Telegram 通知失败，检查代理是否正常：

```bash
curl -x http://127.0.0.1:7890 https://api.telegram.org
```

## 单独使用 claude_monitor.py

如果不需 Telegram 通知，可以单独运行监听脚本：

```bash
# 默认模式（打印到终端）
python claude_monitor.py

# JSON 输出模式
python claude_monitor.py --json

# 静默模式
python claude_monitor.py -q

# 指定项目
python claude_monitor.py -p ~/.claude/projects/-your-project
```
