cc-monitor

[English](#english) | [中文](#chinese)

---

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

[→ Open Dashboard](https://bolunhan.github.io/cc-monitor/)

> 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 /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://:9876/static/install-hooks.sh | SERVER_URL=https://:9876 bash

> 🔐 One-time cert step: Open https://: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: