CC Safety Net is short for Coding CLI Safety Net. It is a PreToolUse hook that blocks destructive commands and access to secrets such as SSH keys and .env files before the tool call runs. It parses what a command does, so flag reordering, shell wrappers, and interpreter one-liners cannot bypass it.
[!NOTE] Full documentation → covers installation, configuration, reference material, guides, and the security model. This README is the short version.
Why this exists
We built CC Safety Net after an agent wiped hours of work with one rm -rf ~/ or git checkout --. Instructions did not stop it. Rules in CLAUDE.md or AGENTS.md can guide an agent, but they cannot enforce a technical limit. CC Safety Net watches relevant tool calls and blocks destructive commands and secret access before they reach the shell. See What is CC Safety Net for the full background.
What's new in v2.0.0
[!TIP] Already running v1? Run
npx -y cc-safety-net@latest updateto upgrade every installed integration to v2. If you defined custom rules under v1, also read Upgrading from an older version.
- Evaluation engine. A canonical command IR, policy snapshots that remain immutable at every nested level, and an ordered guard pipeline now support decision tracing through
explain. - Secret protection. Built-in rules block content access to SSH keys,
.envfiles, cloud credentials, and coding-CLI credential stores through shell commands and file tools. - Always-on protections. Every mode blocks recursive deletion of root or home, Git metadata changes to the
.gitcontrol plane, hooks, worktrees, or submodules, and changes to the user policy file. Overrides do not disable these rules. - Safety presets. The
standard,strict, andparanoidlevels support per-rule overrides and trusted delete allow-paths. Safety-level and capability environment variables can only raise protection.CC_SAFETY_NET_WORKTREEis the one exception. It allows local Git discards in linked worktrees. - Policy GUI.
cc-safety-net guiruns a local, token-authenticated editor with a live preset preview. - Universal installer. Interactive
installanduninstallcommands support all twelve coding CLIs. Theupdatecommand updates installed integrations. - Command-decision audit trail. CC Safety Net records allowed and blocked decisions in local per-project JSONL. It redacts secrets, keeps records for 30 days by default, and shows them through
cc-safety-net logs. - Threat model. SECURITY.md defines the mode contract and resource limits. Its residual-risk registry records decisions for bypass families.
Quick start
You need Node.js 18 or higher.
Run the interactive selector to install CC Safety Net into one or more installed coding CLIs:
npx -y cc-safety-net@latest install
To update every installed integration:
npx -y cc-safety-net@latest update
Keep the @latest qualifier. A bare cc-safety-net spec can run an older cached
copy from the npx cache instead of the current release.
To remove integrations interactively:
npx -y cc-safety-net uninstall
If you use the CLI often, install it globally to get ccsn, a shorter alias for the same commands:
npm install -g cc-safety-net
ccsn doctor
Supported coding CLIs
CC Safety Net supports the coding agent CLIs below on Windows, macOS, and Linux. Automated tests cover the analyzer and some Windows integrations. Other hosts have best-effort Windows support that has not been tested. Amp documents macOS, Linux, and WSL, but not native Windows.
 Amp Code |  Antigravity CLI |  Claude Code |  Codex |
 Cursor |  Gemini CLI |  GitHub Copilot CLI |  Hermes Agent |
 Kimi Code |  OpenClaw |  OpenCode |  Pi |
What it does
| Capability | What it catches |
|---|---|
| Semantic command analysis | Detects the intent of rm -rf on destructive targets, git reset --hard, git checkout --, git push --force, git stash clear, git clean -f, unsafe find -delete, dd, mkfs, and shred. It allows git checkout -b feature but blocks git checkout -- file. |
| Shell wrapper detection | Finds destructive commands inside bash -c, sh -c, and similar wrappers. It analyzes nested wrappers up to 10 levels deep. |
| Interpreter one-liners | Finds destructive code in python -c, node -e, ruby -e, and perl -e one-liners such as os.system("rm -rf /"). |
| Fail-closed by default | Blocks malformed hook input and, in strict mode, commands it cannot parse. Invalid configuration never blocks. CC Safety Net drops an unverifiable rule source and uses protective defaults when it cannot read policy.json. It reports these states in block messages, doctor, the status line, and the GUI. |
| Secret protection | Blocks content access to SSH keys, .env files, ~/.aws, Kubernetes, Docker, and gcloud configuration, and coding-CLI credential stores. The rules apply to shell commands and read, edit, write, and search tools. |
| Custom rules via rulebooks | Lets you add blocking rules at user or project scope. CC Safety Net pins rulebooks fetched from GitHub by SHA-256 digest. |
| Audit logging | Writes allowed and blocked command decisions to local per-project JSONL, redacts secrets, and keeps records for 30 days by default. Browse them with npx cc-safety-net logs, or review them in the Activity view of npx cc-safety-net gui. |
Full rule catalogs: Blocked Commands · Allowed Commands · Secret Protection.
Why not just use a sandbox?
A workspace-writable sandbox still permits git reset --hard, git push --force, and rm -rf . inside the project directory. The operating system sees writes to an allowed path. A sandbox limits where a process can write. CC Safety Net blocks destructive operations inside that allowed area. Use both. See vs Sandboxing.
Safety presets
Set a session safety preset with the GUI npx cc-safety-net gui then navigate to the policy tab:
| Preset | Effect |
|---|---|
| Standard | Blocks recognizable destructive Git and filesystem commands. Allows metadata-only checks of built-in sensitive paths while continuing to block content access. Recommended for normal coding. |
| Strict | Standard, plus blocks dynamic or unparseable commands the analyzer cannot verify safely and metadata-only discovery of built-in sensitive paths. Occasional false positives on advanced shell. |
| Paranoid | Strict, plus blocks rm -rf inside your project and interpreter one-liners. Expect friction; for untrusted agents or high-stakes repos. |
Diagnostics and tracing
# Summarize what is being enforced right now
npx cc-safety-net status
# Verify your installation and run a self-test
npx cc-safety-net doctor
# Trace how a command is analyzed step-by-step
npx cc-safety-net explain "git reset --hard"
# Browse recorded denials from the audit trail (add --all to include allowed commands)
npx cc-safety-net logs
# Review what was blocked and edit your policy in a local web GUI
npx cc-safety-net gui
doctor, explain, and logs support --json for machine-readable output. The audit trail stays on your machine. It records command decisions, but it does not record command output or prompts. Invalid configuration never blocks your agent. CC Safety Net drops unverifiable rule sources and reports each degraded state in the next block message, doctor, the status line, and the GUI banner.
Details: CLI Commands · Explain Trace · Audit Log · Dashboard · Configuration Recovery.
Limitations
CC Safety Net denies a tool call before it runs. It does not enforce filesystem permissions, inspect network egress, or contain a process. Two v2 limits matter. First, the policy and sensitive-path command extractors remain mainly POSIX-oriented. Native PowerShell path expressions such as Get-Content $HOME\.ssh\id_rsa can evade static path extraction. Second, policy-file protection is a best-effort exact-path guard. It does not emulate commands. Use operating-system permissions, a sandbox, or equivalent runtime controls when you need complete protection.
Codex has one integration-specific limit. Its unified exec path is the default on macOS and Linux. It sends a hook payload when a command starts a session, but it sends none for write_stdin. CC Safety Net can inspect and audit the command that opens the session. It cannot inspect or audit text that the model types into the running session. Codex emits no event for that call, so an adapter change cannot close this gap.
SECURITY.md contains the full residual-risk registry. Known Limitations explains what those risks mean in practice.
Upgrading from an older version
Upgrade every installed integration to the current release with one command:
npx -y cc-safety-net@latest update
[!WARNING] If you defined custom rules in a legacy inline config such as
.safety-net.jsonor~/.cc-safety-net/config.json, CC Safety Net no longer loads those files at runtime. Their rules enforce nothing. Normal use does not show this failure because the commands now run. Runnpx -y cc-safety-net rule migrateto convert the rules to the rulebook layout. Then runnpx -y cc-safety-net doctorand confirm that the runtime isready. See the migration guide.
Full documentation
The ccsafetynet.com/docs site contains the full documentation:
| Area | Pages |
|---|---|
| Get started | Introduction · Installation · Quickstart · How It Works · Dashboard |
| Configuration | Modes · Policy · Environment · Custom Rules · Status Line · Configuration Recovery |
| Reference | Blocked Commands · Allowed Commands · Secret Protection · Audit Log · CLI Commands · Explain Trace · Glossary |
| Guides | Architecture · Analysis Engine · Design Principles · Security Model · vs Sandboxing · Integration Architecture · Known Limitations · Troubleshooting |
| Project | Contributing · Security Policy |
Development
See CONTRIBUTING.md to contribute to the project.
The repository tracks all 11 generated files under dist/. They include the library
bundle and its type declarations, the CLI entrypoint, the shared chunks, the vendored Zod copy,
and the Pi, Amp, and OpenClaw adapter files. Run bun run verify:package and
bun run verify:repository-plugin when changing packaging, integrations, or release automation.
License
MIT