CC Safety Net — short for Coding CLI Safety Net — is a PreToolUse hook that blocks destructive commands and access to secrets like SSH keys and .env files, before AI coding agents run them. It parses command semantics, so flag reordering, shell wrappers, and interpreter one-liners can't bypass it.
Note
Full documentation → — installation, configuration, reference, guides, and the security model live on the docs site. This README is the short version.
We learned the hard way that instructions aren't enough to keep AI agents in check. After an agent silently wiped hours of progress with a single rm -rf ~/ or git checkout --, it became clear that soft rules in a CLAUDE.md or AGENTS.md file cannot replace hard technical constraints. CC Safety Net is that constraint: it observes 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.
Tip
Already running v1? One command upgrades every installed integration to v2: npx -y cc-safety-net@latest update. If you defined custom rules under v1, also read Upgrading from an older version.
- Rebuilt evaluation engine — canonical command IR, deeply immutable policy snapshots, and an ordered guard pipeline with intrinsic decision tracing behind
explain. - Secret protection — built-in rules block content access to SSH keys,
.envfiles, cloud credentials, and coding-CLI credential stores, across shell commands and file tools alike. - Always-on catastrophic protections — recursive deletion of root or home, Git metadata mutation (
.gitcontrol plane, hooks, worktrees, submodules), and mutation of the user policy file are blocked in every mode, regardless of overrides. - Safety presets —
standard/strict/paranoidlevels with per-rule overrides, trusted delete allow-paths, and env vars that can only raise protection. - Policy GUI —
cc-safety-net guiserves a local, token-authenticated editor with live preset preview. - Universal installer — interactive
install/uninstallacross all twelve supported agent CLIs, with anupdatecommand for installed integrations. - Command-decision audit trail — allowed and blocked command decisions recorded by default to local per-project JSONL with secret redaction, retained for 30 days by default, browsable via
cc-safety-net logs. - Documented threat model — the SECURITY.md mode contract, explicit resource limits, and a residual-risk registry of adjudicated bypass families.
Prerequisite: 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 installTo update every installed integration:
npx -y cc-safety-net@latest updateThe @latest qualifier matters: a bare cc-safety-net spec can re-run an older
cached copy from the npx cache instead of the current release.
To remove integrations interactively:
npx -y cc-safety-net uninstallIf 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 doctorCC Safety Net works across twelve coding agent CLIs — Claude Code, Antigravity CLI, Codex, Gemini CLI, GitHub Copilot CLI, Kimi Code, OpenCode, Pi, Cursor, Amp Code, Hermes Agent, and OpenClaw — on Windows, macOS, and Linux (the Hermes Agent and OpenClaw integrations are macOS and Linux only). Per-agent instructions, the target flags for scripted non-interactive installs, post-install steps, and per-agent caveats are on Installation; how each integration hooks its agent is on Integration Architecture.
| Capability | What it catches |
|---|---|
| Semantic command analysis | rm -rf on destructive targets, git reset --hard, git checkout --, git push --force, git stash clear, git clean -f, unsafe find -delete, dd/mkfs/shred — by intent, not string pattern. git checkout -b feature (safe) is allowed while git checkout -- file (destructive) is blocked. |
| Shell wrapper detection | Destructive commands hidden in bash -c, sh -c, and similar wrappers, recursively analyzed up to 10 levels deep. |
| Interpreter one-liners | Destructive code in python -c, node -e, ruby -e, perl -e one-liners (e.g. os.system("rm -rf /")). |
| Fail-closed by default | Malformed hook input and unparseable commands (in strict mode) block rather than allow. Invalid config never blocks: an unverifiable rule source is dropped and an unreadable policy.json falls back to protective defaults, both with a warning on every reporting surface. |
| Secret protection | Content access to SSH keys, .env files, ~/.aws, kube/docker/gcloud configs, and coding-CLI credential stores — enforced on shell commands and file tools (read/edit/write/search) alike. |
| Custom rules via rulebooks | Add your own blocking rules at user or project scope, pinned by SHA-256 digest when fetched from GitHub. |
| Audit logging | Allowed and blocked command decisions written to local per-project JSONL with secrets auto-redacted, retained for 30 days by default. Browse them with npx cc-safety-net logs, or triage them in the Activity view of npx cc-safety-net gui. |
Full rule catalogs: Blocked Commands · Allowed Commands · Secret Protection.
A workspace-writable sandbox still permits git reset --hard, git push --force, and rm -rf . inside the project directory, because the OS only sees writes to an allowed path. Sandboxing contains blast radius; CC Safety Net catches the destructive operations sandboxing permits — use both for defense-in-depth. See vs Sandboxing.
Set a session safety preset with CC_SAFETY_NET_LEVEL=standard|strict|paranoid:
| 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. |
Presets supply inherited defaults; policy.json stores only your explicit deviations — per-rule overrides, allow paths, deny paths, worktree mode, and audit retention. Environment variables can only raise protection, never lower it. The full contract is on Modes, Policy, and Environment, or edit everything visually with the local GUI.
# 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 guidoctor, explain, and logs support --json for machine-readable output. The audit trail records command decisions only — never command output or prompts — and stays on your machine. Invalid configuration never blocks your agent: unverifiable rule sources are dropped and every degraded state is reported on the next block message, doctor, the status line, and the GUI banner.
Details: CLI Commands · Explain Trace · Audit Log · Dashboard · Configuration Recovery.
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 bounds worth knowing up front: the policy and sensitive-path command extractors remain primarily POSIX-oriented, so native PowerShell path expressions such as Get-Content $HOME\.ssh\id_rsa can evade static path extraction; and policy-file protection is a best-effort exact-path guard, not command emulation. Use operating-system permissions, a sandbox, or equivalent runtime enforcement when complete protection is required.
The full residual-risk registry lives in SECURITY.md; the practical consequences are on Known Limitations.
Upgrade every installed integration to the current release with one command:
npx -y cc-safety-net@latest updateWarning
If you previously defined custom rules in a legacy inline config (.safety-net.json or ~/.cc-safety-net/config.json), those files are no longer loaded at runtime and their rules are not enforcing anything. Nothing is blocked, so you will not notice this from normal use — the commands those rules used to block now run. Run npx -y cc-safety-net rule migrate to convert them to the rulebook layout, then npx -y cc-safety-net doctor to confirm the runtime is ready. See the migration guide.
All details live on the docs site at ccsafetynet.com/docs:
| 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 |
See CONTRIBUTING.md for details on how to contribute to this project.
Generated distribution ownership is intentionally narrow. Only dist/index.js,
dist/index.d.ts, dist/bin/cc-safety-net.js, and dist/pi/index.js are tracked. Run
bun run verify:build, bun run verify:package, and bun run verify:repository-plugin when
changing packaging, integrations, or release automation.
MIT