cc-monitor

---

🚦 cc-monitor — Cyber Traffic Light for Claude Code & DSH
Claude Code / DSH 赛博红绿灯

→ Open Dashboard

CI runs on the GitLab mirror pipeline. GitHub Actions is disabled in this repository — see .github/workflows/README.md.

Know when Claude needs you — before you waste time staring at the screen.

Physical "Claude Code traffic light" gadgets sell for serious money. cc-monitor is the free, open-source version — it runs on any machine, pushes notifications to your phone and browser, and costs nothing. All you need is an Android phone or a browser tab.

🛡️ Guard your vibe-coding flow. When Claude is working, you're free. The moment it needs approval, hits an error, or finishes a review — you get pinged. No more babysitting the terminal.

---

⚠️ Security Warning

Only install this tool from a trusted source. The hook installer modifies ~/.claude/settings.json — Claude Code's global configuration file. A malicious hook script can steal your Claude API token and gain full access to your Anthropic account. Never install hooks from a server you don't control.

• Always inspect the install script before running it: curl -skSL <url>/static/install-hooks.sh | less
• Verify the source — this repo is the only official distribution
• Do NOT use sudo — the hook scripts do not require root privileges and only modify your user-level Claude Code settings
• Use localhost when the server runs on the same machine (no auth required)

---

Quick Start

Option A: Docker from GHCR (no clone needed)

Pulls the pre-built image from 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

Option B: Docker local build (clone repo)

Build the image yourself from source:

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

💾 Data persistence: all state (sessions, pairing tokens, approved devices, certs) lives in ~/.cc-monitor/docker/data — a plain host folder bind-mounted at /data/.cc-monitor inside the container. It survives docker compose restart, down, down -v, and image upgrades, and is easy to back up. It stays out of ~/.cc-monitor itself so a native cc-monitor on the same host doesn't share/conflict with the same files. If you run compose via sudo, preserve your home directory: sudo env HOME=$HOME docker compose up -d (the Makefile already does this). The server auto-detects the mount and warns at startup when no persistent storage is found.

Option C: Native Python

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

Then: Install Hooks

On the machine where Claude Code runs:

curl -skSL https://<server-ip>:9876/static/install-hooks.sh | SERVER_URL=https://<server-ip>:9876 bash

🔐 One-time cert step: Open https://<server-ip>:9876 in your browser, click Advanced → Proceed to site to trust the self-signed certificate. Required when using the remote dashboard.

Install the DSH Reporter Plugin

On the machine running DeepSeek Harness (DSH), install from npm (the default, published automatically by the GitHub Actions release):

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

Fallback — install from the GitHub release tarball:

bash <(curl -fsSL https://raw.githubusercontent.com/BolunHan/cc-monitor/main/scripts/install-dsh-plugin.sh) https://github.com/BolunHan/cc-monitor/releases/latest/download/dsh-cc-monitor.tgz

Then restart dsh web. Verify with dsh --profile web --dump-config — you should see a cc-monitor row. The plugin appears in DSH Web UI → Settings → Plugins → Plugin configuration, where you can configure Enabled, Server URL, Host, Port, and Installation UID. It defaults to http://127.0.0.1:9876, auto-falls-back to HTTPS, and accepts the local self-signed cert. DSH sessions appear with a blue DSH badge in the same dashboard, next to Claude Code's orange-red CC badge.

---

Web Dashboard

Powerful zero-install monitoring — works from any browser.

Local: Open https://localhost:9876 — connects automatically.

Remote (GitHub Pages): Go to bolunhan.github.io/cc-monitor, open Settings (⚙), enter your server IP and port, then Save & Reconnect.

💡 Browser notifications work as a free alternative to the Android app — enable them when prompted and get pinged on state changes even without your phone nearby.

What you can do

Remote control

cc-monitor is not just a viewer — it is a two-way channel, and the agent is steered from the dashboard.

Approvals. When a hook has a UI connected, its PermissionRequest hook holds the local dialog open and waits for an answer from the dashboard. If nobody answers — or no UI is connected at all — the hook returns immediately and the normal terminal prompt appears, exactly as it would without cc-monitor. That gating is deliberate: remote approval must never slow down the terminal for someone who is sitting at it.

Directives. A directive is queued and handed to the agent by the Stop hook at its next turn boundary, as hook feedback. At that boundary, a connected UI also gets a short window to send a follow-up, so the common case ("it just finished, one more thing…") lands without waiting for another turn.

Stop. Claude Code exposes no external interrupt, so stop is cooperative: the PreToolUse hook denies tool calls and ends the turn. The agent stops touching things and summarizes where it got to. Sending a directive (or pressing Resume) clears the stop.

⚠️ An answer sent after the terminal prompt has already been answered is reported as "Too late — answer at the terminal" rather than silently claiming success.

---

Android App

Turn your phone into a dedicated Claude Code status monitor.

Getting the app

Download the latest APK from Releases and install via ADB:

adb install cc-monitor-app-release.apk

Connecting to a server

LAN Scan (auto-discovery):

1. Make sure the server is running with --host 0.0.0.0 (mDNS is on by default)
2. Open the app — it auto-scans your local network
3. Tap a discovered server to pair

QR Code Scan:

1. In the web dashboard, click ⧉ (Pair Device) to show a QR code
2. In the app, tap Scan QR Code and point your camera
3. Pairing completes automatically

Manual Entry:

1. Tap Manual Entry in the app
2. Enter the server IP, port, and token (from the web dashboard's pairing panel)

Managing servers

Open Settings (⚙) from the dashboard. You'll see:

• Server cards with connection status dots (green = connected, orange = disconnected, grey = inactive)
• Forget button on every server — removes it from your list
• Pair New Server to add another Claude Code instance
• Language switcher (System default / English / 中文)

---

Session States — Your Traffic Light

You get notified instantly via browser push and/or Android notification on every state change that needs your attention.

---

How It Works

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

The server listens for 7 Claude Code hook events, tracks session state in memory, persists to disk, and pushes real-time updates to all connected clients via Server-Sent Events. The web dashboard and Android app render live session cards with color-coded states.

For the full technical reference, see API Reference and Architecture.

---

API Reference

¹ Token via ?token= query parameter (EventSource limitation)
² Requires localhost access

---

Architecture

cc-monitor/
|--  src/cc_monitor/       # Python package (FastAPI server)
|--  hooks/                # Hook scripts (stdlib-only, no deps)
|--  static/               # Web dashboard (vanilla HTML/CSS/JS)
|--  scripts/              # install-hooks.sh, uninstall-hooks.sh, build-dev-docker.sh
|--  android_app/          # Flutter Android app
|--  tests/                # pytest suite (229 tests)
|--  Dockerfile            # Python server image
|--  Dockerfile.dev        # Agent sandbox for development/testing
|--  Dockerfile.flutter    # Flutter build image
|--  docker-compose.yaml   # Docker deployment
+--  docker-compose.dev.yaml  # Dev sandbox (separate port, separate state)

Development

pip install -e ".[dev]"
pytest tests/ -q          # 229 tests
cc-monitor --port 9876    # Start dev server

Testing against a real agent

The host's cc-monitor is often in use, so there is a sandbox: a throwaway container with Claude Code CLI + dsh + cc-monitor on its own port, own state directory, and no shared state with the live instance.

./scripts/build-dev-docker.sh          # build (cached) + start on :9877
./scripts/build-dev-docker.sh --shell  # run an agent inside it

See DEV-DOCKER.md for the caching model, the auth seeding, and the known limitations.

---

🚦 cc-monitor — Claude Code / DSH 赛博红绿灯

→ 打开仪表盘

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

---

快速开始

方案 A：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

方案 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

然后：安装 Hook

在运行 Claude Code 的机器上执行：

curl -skSL https://<服务器IP>:9876/static/install-hooks.sh | SERVER_URL=https://<服务器IP>:9876 bash

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

安装 DSH 上报插件

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

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

备用方式 — 从 GitHub Release tarball 安装：

bash <(curl -fsSL https://raw.githubusercontent.com/BolunHan/cc-monitor/main/scripts/install-dsh-plugin.sh) https://github.com/BolunHan/cc-monitor/releases/latest/download/dsh-cc-monitor.tgz

然后重启 dsh web。运行 dsh --profile web --dump-config 验证，应该能看到 cc-monitor 行。插件会出现在 DSH Web UI → Settings → Plugins → Plugin configuration 中，可配置 Enabled、Server URL、Host、Port 和 Installation UID。默认上报到 http://127.0.0.1:9876，并会自动回退到 HTTPS、接受本机自签名证书。DSH 会话会在同一仪表盘中显示蓝色 DSH 徽章，与 Claude Code 的橙红色 CC 徽章并列。

---

Web 仪表盘

功能强大的零安装监控 — 任何浏览器都能用。

本地访问： 打开 https://localhost:9876 — 自动连接。

远程访问（GitHub Pages）： 前往 bolunhan.github.io/cc-monitor，打开 设置（⚙），输入服务器 IP 和端口，然后 保存并重连。

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

功能一览

远程控制

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 / 中文）

---

会话状态 — 你的红绿灯

每次需要你关注的状态变化，你都会立即通过浏览器推送和/或 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 接口

---

架构

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  # 在沙箱内运行智能体