CC-Monitor

English | 简体中文

Ever let an AI agent write code for you and had no idea what it actually did to your machine along the way? Give this a try. It monitors what Claude Code does on your machine — file reads/writes, shell command execution, network access — and blocks or asks for confirmation on high-risk operations, so an AI coding agent can't quietly damage your system or leak data. Everything is audit-logged. The technical design doc is available in English and Chinese. For what risks installing this actually carries, what third-party modules it depends on, and where your data actually goes, see SECURITY.md (Chinese).

Every release — what was added, changed and fixed — is recorded in CHANGELOG.md (Chinese); the current release is v2.0.

🧪 Experimental features (dev branch): master monitors Claude Code only. The dev branch is extending the detection surface to other AI coding agents — Codex CLI, Gemini CLI, Cursor, OpenCode, ZCode, Antigravity CLI and Grok CLI plug into the same rules, approval desk and audit log through their own hooks / plugin; the system-layer eBPF probe recognises every agent's process tree via an "agent registry" and gains file-level syscalls (write / delete / rename / mkdir), listening-port observation, directory-fd tracking (relative paths from rm -r / mkdir -p resolved to absolute ones), session attribution for kernel events and explicit CC-Monitor run -- binding; AI Tap parses Claude Code / Antigravity CLI / Codex session files. Everything except Claude Code is in an experimental / testing stage (implemented from each vendor's docs or source; Antigravity CLI has had one real-machine round, the rest have not been verified on real installs) — not recommended for production. See the dev branch README, MULTI-AGENT.md (usage and internals) and DESIGN-multi-agent.md (design), both in Chinese. To try it: git checkout dev, or git worktree add ../CC-Monitor-dev dev and run it with a separate CC_MONITOR_HOME and port so the master install is untouched.

Core capabilities at a glance

• Two independent layers of monitoring: Claude Code hooks capture semantic detail; a Linux eBPF / macOS nettop probe cross-verifies at the kernel/system level, independent of the hooks — so a bypassed or tampered hook config doesn't mean monitoring silently stops.
• 86 built-in detection rules, auto-triaged by risk: high-risk operations get blocked outright (rm -rf, reverse shells, writing SSH keys…), medium-risk ones pop a confirmation prompt, low-risk ones are logged silently — you're not babysitting every single action.
• Full audit trail: every tool call's command, path, arguments, and decision are logged to SQLite in full. CC-Monitor tail gives you a live, syntax-highlighted view (command name, arguments, strings, pipes each get their own color) with one command.
• Bypass detection: cross-checks commands the system-layer probe actually observed against what the application-layer hooks recorded, specifically to catch the harder-to-notice case of monitoring being silently disabled.
• Cross-workdir behavior detection: regex rules can't see the cwd, so this layer fills the gap — every path a tool call is about to touch (file tools' file_path; Bash commands split into sub-commands with paths resolved, cd tracked, and redirects / rm/cp/tee-style writes recognized) is resolved to an absolute path and compared against the current project directory. Anything outside is tiered by location (hidden home-dir config/credentials, other users' homes, system directories, other project directories) × read/write: writes to sensitive locations prompt for confirmation, everything else is logged. Review them with CC-Monitor workdir or the "Cross-workdir operations" home-page card.
• Network visibility: eBPF captures the destination IP:port of every connect() call directly — no TLS termination, no CA certificate to install — with a connection detail table, GeoIP lookups, and a WebGL2 world map in the Web UI.
• A full Web UI dashboard: home-page stat cards, an AI approval desk (confirm from the web page, the terminal, or a desktop notification — whichever answers first wins), Claude Tap (reconstructs full conversations without packet capture), and live account quota display, all in one page.
• Cross-platform: works on both Linux and macOS (including real Apple Silicon M4 hardware verification), with the core feature set consistent across both.

Screenshots

Home overview

Session list drilldown	Event type breakdown

Blocked high-risk operations	Audit log

Quick Install

git clone https://github.com/cn0xroot/CC-Monitor.git
cd CC-Monitor
./install.sh

install.sh runs 5 steps in order: the ccstatusline terminal statusline, hook registration, Web UI dependencies, a system-layer probe check, and the GeoIP database — each one idempotent and independently skippable (--skip-ccstatusline / --skip-geoip), never overwriting anything you already have configured. Then run ./start.sh to launch the Web UI.

If you only want the core interception/audit capability and don't need the Web UI or any of that, this one step is enough on its own:

python3 install.py

It does exactly one thing — registers the hooks into Claude Code's ~/.claude/settings.json. No npm or Python dependencies get installed (cc_monitor/ itself is standard-library-only Python). Once that's done, the CC-Monitor tail/rules/stats/verify CLI commands already work; the Web UI is an entirely optional, separate add-on you can install later whenever you want it. For the exact flags each script takes, what install.sh's 5 steps actually do, and installing to a system path (make install), see the Installation section below.

Intervention levels: picking one

Once installed, you decide how strict the tool is. There are three levels, and exactly one is active at any time.

Think of it as a guard at the door:

In concrete terms:

• Enforcing is the default; it's what you get if you change nothing after installing. Operations matching a high-risk rule are blocked outright, things like rm -rf /, reverse shells, or writing into ~/.ssh. Medium-risk matches pop a confirmation and only proceed if you say so. Everything else is logged silently.
• Permissive records without stopping. Rules are still evaluated and the risk level and matched rule still land in the audit log, it just never blocks and never prompts. Two situations call for it: you're heads-down and don't want confirmation dialogs interrupting you but do want to know afterwards what the agent did; or you just installed the tool and don't yet know which rules your normal workflow trips, so you run it this way for a couple of days and read the log before tightening anything.
• Off is the only level that genuinely stops auditing. Nothing is evaluated, nothing is recorded, exactly as if the tool weren't installed. Its use is narrow: you suspect CC-Monitor itself is causing a problem and want to compare with it out of the picture.

Permissive and Off are the easy pair to confuse. Neither one will stop you. The difference is whether there's anything to look at afterwards. Permissive keeps the log filling; Off leaves a blank stretch you can never go back and inspect. So if you just want fewer interruptions, pick Permissive, not Off.

You can switch from the command line:

CC-Monitor audit start        # Enforcing
CC-Monitor audit permissive   # Permissive (the old name, pause, still works)
CC-Monitor audit stop         # Off
CC-Monitor audit status       # Show the current level

Or in the browser, on the left of the home page toolbar: three levels side by side, click one to switch, and the active one is highlighted in its color. Switching to Off asks once more first, because that's the level that leaves a gap in the audit trail. A matching status pill also sits permanently in the top bar, so you can tell the current level without going back to the home page.

One thing to know: the system-layer probe is not controlled by this switch. As long as the probe is running it keeps recording command execution and network connections at the kernel level, whichever level you pick. That's deliberate. The probe's whole value is observing independently of the hooks, so shutting it off alongside them would defeat the point.

Web UI

webui/ is a standalone Node.js service that provides a browser UI:

cd webui
npm install
node server.js          # listens on http://127.0.0.1:9999 by default, localhost-only

• Home:
  • Intervention level: Enforcing / Permissive / Off as a segmented control, so all three are visible at once and clicking one switches straight to it, with the active one highlighted in its color (purple / green / yellow). A line below the control explains whichever