BolunHan/cc-monitor

🚦 cc-monitor — 适用于 Claude Code 和 DSH 的赛博红绿灯Claude Code / DSH 赛博红绿灯

→ 打开仪表盘

gitlab

CI 在 GitLab 镜像流水线上运行。 此仓库中 GitHub Actions 已禁用 —
请参阅 .github/workflows/README.md。

在 Claude 需要你时及时知晓 — 不再浪费时间盯着屏幕。

实体的“Claude Code 红绿灯”小装置售价不菲。cc-monitor 是免费、开源版本 — 它可在任何机器上运行，将通知推送到你的手机和浏览器，且完全免费。你只需要一部 Android 手机或一个浏览器标签页。

🛡️ 守护你的 vibe-coding 心流。 当 Claude 工作时，你自由自在。当它需要批准、遇到错误或完成审查的那一刻 — 你会收到提醒。无需再守着终端。

⚠️ 安全警告

仅从可信来源安装此工具。 hook 安装程序会修改 ~/.claude/settings.json — Claude Code 的全局配置文件。恶意 hook 脚本可能窃取你的 Claude API token，并获得对你 Anthropic 账户的完全访问权限。切勿从你无法控制的服务器安装 hook。

- 务必检查安装脚本后再运行：curl -skSL /static/install-hooks.sh | less
- 验证来源 — 此仓库是唯一的官方分发渠道
- 请勿使用 sudo — hook 脚本不需要 root 权限，仅修改你的用户级 Claude Code 设置
- 当服务器运行在同一台机器上时，使用 localhost（无需认证）

快速开始

选项 A：从 GHCR 使用 Docker（无需克隆）

从 GitHub Container Registry 拉取预构建镜像：

mkdir cc-monitor && cd cc-monitor
curl -O https://raw.githubusercontent.com/BolunHan/cc-monitor/main/docker-compose.yaml
docker compose up -d

选项 B：Docker 本地构建（克隆仓库）

从源码自行构建镜像：

git clone https://github.com/BolunHan/cc-monitor.git
cd cc-monitor
docker build -t ghcr.io/bolunhan/cc-monitor:latest .
docker compose up -d

💾 数据持久化： 所有状态（会话、配对令牌、
已批准设备、证书）都存放在 ~/.cc-monitor/docker/data — 这是一个普通的主机文件夹，
以 bind mount 方式挂载到容器内的 /data/.cc-monitor。它能在
docker compose restart、down、down -v 以及镜像升级后保留，且易于
备份。它不放在 ~/.cc-monitor 本身中，这样同一主机上的原生 cc-monitor
就不会共享/冲突相同的文件。如果你通过 sudo 运行
compose，请保留你的主目录：
sudo env HOME=$HOME docker compose up -d（Makefile 已处理此问题）。
服务器会自动检测挂载点，并在启动时未找到持久化存储时发出警告。

选项 C：原生 Python

git clone https://github.com/BolunHan/cc-monitor.git
cd cc-monitor
pip install .
cc-monitor --port 9876 --host 0.0.0.0

接下来：安装 Hooks

在运行 Claude Code 的机器上：
curl -skSL https://:9876/static/install-hooks.sh | SERVER_URL=https://:9876 bash

🔐 一次性证书步骤： 在浏览器中打开 https://:9876，点击 高级 → 继续访问该网站 以信任自签名证书。使用远程仪表板时必须执行此操作。

安装 DSH Reporter 插件

在运行 DeepSeek Harness (DSH) 的机器上，从 npm 安装（默认方式，由 GitHub Actions 发布流程自动发布）：

dsh plugin --profile web add dsh-cc-monitor

备选方案——从 GitHub 发布 tarball 安装：

bash  💡 浏览器通知 可作为 Android 应用的免费替代方案——在提示时启用它们，即使手机不在身边，也能在状态变化时收到通知。

你可以做什么

| 操作               | 方法                                                                  |
| -------------------- | -------------------------------------------------------------------- |
| 查看所有会话     | Active / Complete / Archived 标签页，带实时状态细分          |
| 获取通知         | 在空闲、待审查、待批准时发送浏览器推送通知 |
| 回答批准请求 | 会话卡片上会出现待处理提示——Allow / Deny（或为 AskUserQuestion 选择一个选项，批准 / 拒绝计划） |
| 发送指令 | 在会话卡片的输入框中输入并按 Enter                   |
| 停止任务      | 会话卡片上的 Stop 按钮；Resume（或发送指令）可解除它 |
| 配对设备         | 用于 Android 应用的二维码 + 6 位数字批准流程                  |
| 管理钩子             | 从设置面板一键安装 / 卸载 / 检查                                     |
| 切换语言             | 顶栏中的 EN / 中文 切换                                          |

远程控制

cc-monitor 不仅仅是一个查看器——它是一个双向通道，智能体由仪表盘来操控。

审批。 当有 UI 连接到某个钩子时，其 PermissionRequest 钩子会保持本地对话框打开，并等待来自仪表盘的答复。如果无人答复——或者根本没有连接任何 UI——该钩子会立即返回，正常的终端提示符会出现，与没有 cc-monitor 时完全一样。这种门控是刻意设计的：远程审批绝不能拖慢坐在终端前的人的终端操作。

指令。 指令会被排队，并在下一个回合边界由 Stop 钩子作为钩子反馈交给智能体。在该边界处，已连接的 UI 也会获得一个短暂的时间窗口来发送后续消息，因此常见情况（“它刚完成，还有一件事……”）无需等待下一个回合即可送达。

停止。 Claude Code 不提供外部中断，因此停止是协作式的：PreToolUse 钩子会拒绝工具调用并结束该回合。智能体停止改动，并总结它进行到了哪里。发送指令（或按下 Resume）会清除停止状态。

⚠️ 在终端提示符已经被答复之后才发送的答复，会被报告为 “太晚了——请在终端答复”，而不是默默声称成功。

Android 应用

把你的手机变成专用的 Claude Code 状态监视器。

获取应用

从 Releases 下载最新的 APK，并通过 ADB 安装：bash
adb install cc-monitor-app-release.apk

连接到服务器

局域网扫描（自动发现）：
1. 确保服务器以 --host 0.0.0.0 运行（mDNS 默认开启）
2. 打开应用——它会自动扫描你的本地网络
3. 点击发现的服务器进行配对

二维码扫描：
1. 在 Web 仪表盘中，点击 ⧉（配对设备）以显示二维码
2. 在应用中，点击 扫描二维码 并将摄像头对准它
3. 配对会自动完成

手动输入：
1. 在应用中点击 手动输入
2. 输入服务器 IP、端口和令牌（来自 Web 仪表盘的配对面板）

管理服务器

从仪表盘打开 设置（⚙）。你会看到：
- 服务器卡片，带有连接状态圆点（绿色 = 已连接，橙色 = 已断开，灰色 = 未激活）
- 每个服务器上的 忘记 按钮——将其从你的列表中移除
- 配对新服务器 以添加另一个 Claude Code 实例
- 语言 切换器（系统默认 / English / 中文）

会话状态——你的红绿灯

| 灯 | 状态              | 含义                                              | 你的操作            |
| ----- | ------------------ | ---------------------------------------------------------- | -------------------- |
| 🔵     | working          | Claude 正在编码、运行工具、生成输出         | 去喝杯咖啡 ☕     |
| 🟢     | pending_review   | Claude 已完成——输出已就绪，等待你查看                     | 查看结果   |
| 🟡     | pending_approval | Claude 需要权限（工具批准、权限提示） | 批准或拒绝      |
| ⚪     | idle             | 没有任何活动——会话休眠                        | 发送下一条提示 |
| ✅     | all_done         | 会话已结束                                              | 归档并继续  |

你会立即收到通知，通过浏览器推送和/或 Android 通知，在每次需要你关注的状态变化时。

工作原理

Claude Code                    cc-monitor                  Web Dashboard
(hooks)                        Server                    Android App
|                             |  |
|  POST /api/event            |  |  SSE stream
+-----------------------------+  +---------------------->
|
+-- State files (~/.cc-monitor/)
+-- mDNS (LAN discovery)
+-- TLS + Token Auth

服务器监听 7 个 Claude Code hook 事件，在内存中跟踪会话状态，持久化到磁盘，并通过 Server-Sent Events 向所有连接的客户端推送实时更新。Web 仪表盘和 Android 应用会渲染带有颜色编码状态的实时会话卡片。

有关完整的技术参考，请参阅 API Reference 和 Architecture。

API Reference

| Method   | Path                                  | Auth   | Description                                    |
| -------- | ------------------------------------- | ------ | ---------------------------------------------- |
| POST   | /api/event                          | Yes    | 提交一个 hook 事件                            |
| GET    | /api/status                         | Yes    | 所有会话                                   |
| GET    | /api/status/                    | Yes    | 单个会话                                 |
| GET    | /api/stream                         | Token¹ | SSE 流（state_update + 每 3 秒心跳） |
| GET    | /api/version                        | No     | 服务器版本                                 |
| GET    | /api/hooks-status                   | Yes    | Hook 安装状态                       |
| POST   | /api/install-hooks                  | Yes²   | 全局安装 hooks                         |
| POST   | /api/uninstall-hooks                | Yes²   | 移除 cc-monitor hooks                        |
| POST   | /api/session//archive           | Yes    | 归档会话                                |
| POST   | /api/session//unarchive         | Yes    | 取消归档会话                              |
| POST   | /api/session//complete          | 是     | 将会话标记为完成                               |
| POST   | /api/session//respond           | 是     | 应答一个待处理的请求                           |
| POST   | /api/session//directive         | 是     | 为 agent 排队一条指令                          |
| GET    | /api/session//directive/next    | 是     | 长轮询获取指令（Stop hook）                    |
| POST   | /api/session//stop              | 是     | 请求 agent 停止                                |
| POST   | /api/session//resume            | 是     | 清除停止请求                                   |
| GET    | /api/request//decision         | 是     | 长轮询获取审批结果（PermissionRequest hook）   |
| GET    | /api/auth/pair/qr                   | 否     | QR 配对载荷                                    |
| POST   | /api/auth/pair/request              | 否     | 提交配对请求                                   |
| GET    | /api/auth/pair/request//status  | 否     | 轮询请求状态                                   |
| POST   | /api/auth/pair/request//approve | 否     | 批准（仅限 localhost）                         |
| DELETE | /api/auth/devices/              | 是     | 撤销设备                                       |
| GET    | /api/auth/devices                   | 是     | 列出已配对的设备                               |

¹ 通过 ?token= 查询参数传递令牌（EventSource 限制）
² 需要 localhost 访问权限

架构

cc-monitor/
|--  src/cc_monitor/       # Python 包（FastAPI 服务器）
|--  hooks/                # Hook 脚本（仅用标准库，无依赖）
|--  static/               # Web 仪表盘（原生 HTML/CSS/JS）
|--  scripts/              # install-hooks.sh、uninstall-hooks.sh、build-dev-docker.sh
|--  android_app/          # Flutter Android 应用
|--  tests/                # pytest 测试套件（229 个测试）
|--  Dockerfile            # Python 服务器镜像
|--  Dockerfile.dev        # 用于开发/测试的 Agent 沙箱
|--  Dockerfile.flutter    # Flutter 构建镜像
|--  docker-compose.yaml   # Docker 部署
+--  docker-compose.dev.yaml  # 开发沙箱（独立端口、独立状态）

开发
bash
pip install -e ".[dev]"
pytest tests/ -q          # 229 个测试
cc-monitor --port 9876    # 启动开发服务器

针对真实 agent 进行测试

宿主机的 cc-monitor 经常处于使用中，因此提供了一个沙箱：一个一次性的
容器，内含 Claude Code CLI + dsh + cc-monitor，使用独立端口、独立状态
目录，且与线上实例不共享任何状态。
bash
./scripts/build-dev-docker.sh          # 构建（带缓存）+ 在 :9877 上启动
./scripts/build-dev-docker.sh --shell  # 在其中运行一个 agent

关于缓存模型、认证种子数据以及已知限制，请参阅 DEV-DOCKER.md。

🚦 cc-monitor — Claude Code / DSH 赛博红绿灯
→ 打开仪表盘

gitlab

CI 运行在 GitLab 镜像流水线上。 本仓库已停用 GitHub Actions — 见
.github/workflows/README.md。

Claude 需要你的时候，第一时间知道 — 不再白白盯着屏幕浪费时间。

市面上那些“Claude Code 物理红绿灯”小玩意卖得可不便宜。cc-monitor 是免费的、开源的替代方案 — 跑在任何机器上，推送到你的手机和浏览器，一毛钱不花。你只需要一台 Android 手机或一个浏览器标签页。

🛡️ 守护摸鱼时光安全，及时提醒手动接管 Claude Code。 Claude 干活时你自由，需要审批、出错、或完成审查的那一刻 — 你立刻收到通知。再也不用守着终端。

⚠️ 安全警告

仅从可信来源安装此工具。 Hook 安装脚本会修改 ~/.claude/settings.json — Claude Code 的全局配置文件。恶意 hook 脚本可以窃取你的 Claude API token，获得对你 Anthropic 账户的完全访问权限。切勿从不受你控制的服务器安装 hook。

- 务必先检查安装脚本：curl -skSL /static/install-hooks.sh | less
- 验证来源 — 此仓库是唯一的官方分发渠道
- 切勿使用 sudo — hook 脚本无需 root 权限，仅修改用户级别的 Claude Code 配置
- 优先使用 localhost — 当服务器运行在同一台机器上时无需认证

快速开始

方案 A：Docker（无需克隆仓库）

从 GitHub Container Registry 拉取预构建镜像：
bash
mkdir cc-monitor && cd cc-monitor
curl -O https://raw.githubusercontent.com/BolunHan/cc-monitor/main/docker-compose.yaml
docker compose up -d

方案 B：Docker 本地构建（克隆仓库）

从源码自行构建镜像：
bash
git clone https://github.com/BolunHan/cc-monitor.git
cd cc-monitor
docker build -t ghcr.io/bolunhan/cc-monitor:latest .
docker compose up -d

方案 C：原生 Python
bash
git clone https://github.com/BolunHan/cc-monitor.git
cd cc-monitor
pip install .
cc-monitor --port 9876 --host 0.0.0.0

然后：安装 Hook

在运行 Claude Code 的机器上执行：bash
curl -skSL https://:9876/static/install-hooks.sh | SERVER_URL=https://:9876 bash

🔐 一次性证书步骤： 在浏览器中打开 https://:9876，点击 高级 → 继续访问 以信任自签名证书。使用远程仪表盘时必须执行此步骤。

安装 DSH 上报插件

在运行 DeepSeek Harness（DSH）的机器上，从 npm 安装（默认方式，由 GitHub Actions 发布自动发布）：
bash
dsh plugin --profile web add dsh-cc-monitor

备用方式 — 从 GitHub Release tarball 安装：
bash
bash  💡 浏览器通知 可作为 Android 应用的免费替代 — 被提示时启用，即可在状态变化时收到提醒，即使手机不在身边。

功能一览

| 功能             | 操作方式                                                 |
| ---------------- | -------------------------------------------------------- |
| 查看所有会话     | Active / Complete / Archived 标签页，含实时状态统计      |
| 接收通知         | 浏览器推送通知（idle、pending review、pending approval） |
| 远程审批     | 待审批请求直接显示在会话卡片上 —— 允许 / 拒绝（AskUserQuestion 可选具体选项，计划则可批准 / 驳回） |
| 发送指令     | 在会话卡片的输入框中输入后回车                           |
| 停止任务     | 会话卡片上的「停止」按钮；「继续」或发送指令可解除       |
| 配对设备         | 二维码 + 6 位数字审批流程（供 Android 应用使用）         |
| 管理 Hook        | 设置面板中一键安装 / 卸载 / 检查                         |
| 切换语言         | 顶部 EN / 中文 切换按钮                                  |

远程控制

cc-monitor 不只是查看器 —— 它是一条双向通道，可以在仪表盘上直接操控智能体。

审批。 当有 UI 连接时，PermissionRequest hook 会挂起本地对话框，等待仪表盘给出答复。
若无人应答（或根本没有 UI 连接），hook 会立即返回，终端照常弹出原生提示 ——
这一取舍是刻意的：远程审批绝不能让坐在终端前的人变慢。

指令。 指令会先入队，由 Stop hook 在下一个回合边界作为 hook 反馈交给智能体。
在该边界时刻，已连接的 UI 还会获得一小段窗口期来发送后续消息，
因此最常见的情形（「刚做完，再加一件事…」）无需等到下一回合。

停止。 Claude Code 没有对外暴露中断接口，因此停止是协作式的：
PreToolUse hook 拒绝工具调用并结束当前回合。智能体会停止一切操作并总结当前进展。
发送指令（或点击「继续」）即可解除停止状态。

⚠️ 若在终端提示已被回答之后才提交答复，界面会明确提示
「已超时 — 请在终端回答」，而不是默默假装成功。

Android 应用

将手机变成专属的 Claude Code 状态监视器。

获取应用

从 Releases 下载最新 APK，通过 ADB 安装：
adb install cc-monitor-app-release.apk

连接服务器

局域网扫描（自动发现）：
1. 确保服务器以 --host 0.0.0.0 运行（mDNS 默认开启）
2. 打开应用 — 自动扫描本地网络
3. 点击发现的服务器进行配对

二维码扫描：
1. 在 Web 仪表盘中，点击 ⧉（配对设备）显示二维码
2. 在应用中，点击 扫描二维码，将摄像头对准二维码
3. 配对自动完成

手动输入：
1. 在应用中点击 手动输入
2. 输入服务器 IP、端口和 token（从 Web 仪表盘配对面板获取）

管理服务器

从仪表盘打开 设置（⚙），你将看到：
- 服务器卡片 — 带连接状态圆点（绿色 = 已连接，橙色 = 已断开，灰色 = 未激活）
- 移除按钮在每个服务器上 — 从列表中删除
- 配对新服务器 — 添加另一个 Claude Code 实例
- 语言切换（跟随系统 / English / 中文）

会话状态 — 你的红绿灯

| 灯光 | 状态               | 含义                                  | 你该做什么           |
| ---- | ------------------ | ------------------------------------- | -------------------- |
| 🔵    | working          | Claude 正在写代码、执行工具、生成输出 | 去喝杯咖啡 ☕         |
| 🟢    | pending_review   | Claude 完成 — 输出等待审查            | 检查结果             |
| 🟡    | pending_approval | Claude 需要权限（工具审批、权限提示） | 批准或拒绝           |
| ⚪    | idle             | 无活动 — 会话休眠                     | 发送下一条提示       |
| ✅    | all_done         | 会话已结束                            | 归档，继续下一个任务 |

每次需要你关注的状态变化，你都会立即通过浏览器推送和/或 Android 通知收到提醒。

工作原理

Claude Code                    cc-monitor                  Web 仪表盘
(hooks)                        Server                    Android 应用
|                             |  |
|  POST /api/event            |  |  SSE stream
+-----------------------------+  +---------------------->
|
+-- 状态文件 (~/.cc-monitor/)
+-- mDNS (局域网发现)
+-- TLS + Token 认证

服务器监听 7 个 Claude Code hook 事件，在内存中追踪会话状态，持久化到磁盘，并通过 Server-Sent Events 向所有连接的客户端推送实时更新。Web 仪表盘和 Android 应用渲染带有颜色编码状态的实时会话卡片。

完整技术参考见 API 接口 和 架构。

API 接口
| 方法     | 路径                                  | 说明                                           |
| -------- | ------------------------------------- | ---------------------------------------------- |
| POST   | /api/event                          | 提交 hook 事件                                 |
| GET    | /api/status                         | 所有会话状态                                   |
| GET    | /api/status/                    | 单个会话状态                                   |
| GET    | /api/stream                         | SSE 实时推送（state_update + 每 3s heartbeat） |
| GET    | /api/version                        | 服务器版本                                     |
| GET    | /api/hooks-status                   | 检查 hook 安装状态                             |
| POST   | /api/install-hooks                  | 安装 hook 到全局配置                           |
| POST   | /api/uninstall-hooks                | 移除 cc-monitor hook                           |
| POST   | /api/session//archive           | 归档会话                                       |
| POST   | /api/session//unarchive         | 取消归档                                       |
| POST   | /api/session//complete          | 标记会话完成                                   |
| POST   | /api/session//respond           | 答复待审批请求                                 |
| POST   | /api/session//directive         | 向智能体投递指令                               |
| GET    | /api/session//directive/next    | 长轮询等待指令（Stop hook 调用）               |
| POST   | /api/session//stop              | 请求智能体停止                                 |
| POST   | /api/session//resume            | 解除停止                                       |
| GET    | /api/request//decision         | 长轮询等待审批结果（PermissionRequest hook 调用） |
| GET    | /api/auth/pair/qr                   | 二维码配对数据                                 |
| POST   | /api/auth/pair/request              | 提交配对请求                                   |
| GET    | /api/auth/pair/request//status  | 查询请求状态                                   |
| POST   | /api/auth/pair/request//approve | 批准配对（仅限 localhost）                     |
| DELETE | /api/auth/devices/              | 撤销设备                                       |
| GET    | /api/auth/devices                   | 列出已配对设备                                 |

架构

cc-monitor/
|--  src/cc_monitor/       # Python 包（FastAPI 服务器）
|--  hooks/                # Hook 脚本（纯 stdlib，无依赖）
|--  static/               # Web 仪表盘（原生 HTML/CSS/JS）
|--  scripts/              # install-hooks.sh, uninstall-hooks.sh, build-dev-docker.sh
|--  android_app/          # Flutter Android 应用
|--  tests/                # pytest 测试套件（229 个测试）
|--  Dockerfile            # Python 服务器镜像
|--  Dockerfile.dev        # 开发/测试用智能体沙箱
|--  Dockerfile.flutter    # Flutter 构建镜像
|--  docker-compose.yaml   # Docker 部署
+--  docker-compose.dev.yaml  # 开发沙箱（独立端口、独立状态）

开发
pip install -e ".[dev]"
pytest tests/ -q          # 229 个测试
cc-monitor --port 9876    # 启动开发服务器

用真实智能体做测试

主机上的 cc-monitor 经常正在被使用，因此提供了一个沙箱：
一个内含 Claude Code CLI + dsh + cc-monitor 的一次性容器，
使用独立端口、独立状态目录，与线上实例不共享任何状态。

./scripts/build-dev-docker.sh          # 构建（走缓存）并在 :9877 启动
./scripts/build-dev-docker.sh --shell  # 在沙箱内运行智能体

缓存模型、登录态注入方式与已知限制见 DEV-DOCKER.md。