# claude code watchdog

**Repository Path**: catberus/claude-code-watchdog

## Basic Information

- **Project Name**: claude code watchdog
- **Description**: 实时监控claude code的运行情况
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-30
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Subagent Watchdog

Claude Code Subagent 实时监控面板，基于 Hook 驱动。

## 功能

- **实时状态监控**：自动检测 session 启动/结束，追踪 main agent 和 subagent 状态
- **Hook 驱动架构**：通过 Claude Code Hook 事件（SessionStart/PreToolUse/SubagentStart 等）被动接收状态变化，非侵入式
- **JSONL 心跳检测**：轮询 subagent 日志文件大小变化，自动检测卡死/空闲状态
- **实时日志查看**：点击 📋 图标查看 subagent 完整日志，支持自动轮询刷新
- **内存自动清理**：Session 结束后自动清理内存条目
- **支持 claude -p**：兼容程序化模式（`claude -p`）的 hook 触发

## 快速开始

```bash
# 1. 安装依赖（无，纯 Node.js）
node install.js

# 2. 启动（自动检测 hook 安装 + 启动 watchdog）
node watchdog-cli-v3.js

# 3. 打开浏览器
open http://localhost:9876
```

## 命令

```bash
node watchdog-cli-v3.js           # 检查 hooks + 启动 watchdog
node watchdog-cli-v3.js --install # 强制安装 hooks
node watchdog-cli-v3.js --stop    # 停止 watchdog
node watchdog-cli-v3.js --status  # 查看当前状态
node watchdog-cli-v3.js --uninstall # 卸载 hooks
```

## 架构

```
Claude Code ──(Hook)──> hook-wrapper-v2.sh ──> hook-handler-v2.js ──HTTP──> watchdog-v2.js:9876
                                                                        │
                                                                        ▼
                                                                  dashboard-v2.html/js
                                                                        │
                                                                        ▼ (poll /api/log)
                                                                dashboard modal (auto-scroll)
```

### 文件说明

| 文件 | 功能 |
|------|------|
| `watchdog-v2.js` | 主服务器：Hook 接收 + 状态管理 + HTTP API |
| `watchdog-cli-v3.js` | CLI 入口：hook 检查/安装 + watchdog 启动 |
| `install-hooks-v2.js` | Hook 安装/卸载：写入项目级 `.claude/settings.json` |
| `hook-handler-v2.js` | Hook 转发器：接收 Claude Code hook JSON，POST 到 watchdog |
| `hook-wrapper-v2.sh` | Bash 包装器：后台化 node 进程，2-5ms 退出 |
| `dashboard-v2.html` | 前端页面：暗色主题，实时状态面板 |
| `dashboard-v2.js` | 前端逻辑：10s 刷新 + 2s 日志轮询 + 自动滚动 |

### Hook 事件

| Hook | 触发时机 | 行为 |
|------|----------|------|
| SessionStart | session 开始 | 注册 session + main agent |
| SessionEnd | session 结束 | 标记完成 → 5s 后清理 |
| PreToolUse | 每次 tool 调用 | 刷新 main agent 心跳 |
| PostToolUse | tool 执行完成 | 刷新 main agent 心跳 |
| SubagentStart | subagent 启动 | 注册 subagent |
| SubagentStop | subagent 完成 | 标记 subagent 为 completed |
| Stop | agent 回复完成 | 标记 main agent 为 idle |

## 技术栈

- Node.js 原生（无外部依赖）
- 纯 HTTP + 静态文件服务
- 前端：原生 JS，无框架

## License

MIT