Skip to main content
CC Safety Net installs as a plugin, extension, or hook inside your coding agent. You do not need a persistent service or daemon. Some integrations start a short-lived hook subprocess for each check. Most integrations run on Windows, macOS, and Linux. They detect the host operating system for path handling and command resolution. On Windows, this includes case-insensitive paths and cmd.exe or PowerShell resolution through COMSPEC and PATHEXT. The install commands and the interactive picker also resolve agent CLIs that npm installs as .cmd shims on Windows, so commands like install --codex find them. CI runs the same full check on windows-latest that it runs on Linux and macOS: lint, type checks, and the whole test suite, with three test cases skipped on Windows. Those tests exercise the analyzer and the integration code, not each coding agent running on Windows. Amp’s own manual documents macOS, Linux, and WSL rather than native Windows. The Hermes Agent and OpenClaw integrations run only on macOS and Linux. They use the POSIX home-directory paths ~/.hermes and ~/.openclaw and do not support Windows paths. Install Node.js 18 or later before you start. The examples use npx to run CLI subcommands. Use cc-safety-net install <target-flag> to install one integration and cc-safety-net uninstall <target-flag> to remove it. Use cc-safety-net update to refresh all installed integrations.

​
Install interactively

Run the installer with no target flag to get an interactive multi-select over the coding CLIs detected on your machine:
In the selector, Space selects a target, Enter confirms, u switches to updating every installed integration instead, and q or Esc cancels without changing anything. The @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, so every install, uninstall, and update command on this page pins it. To remove integrations the same way:
If you use the CLI often, install it globally to get ccsn, a shorter alias for the same commands:
The alias ships with the global install; npx runs use the full cc-safety-net name.

​
Update installed integrations

To refresh every installed integration in place, run:
update detects the integrations already installed on your machine, including disabled ones. It runs each install path again in update mode. The command reports an integration as skipped when it cannot find the agent CLI. If no integrations are installed, it tells you to run cc-safety-net install first. Pressing u in the interactive installer runs the same update. update is also the upgrade path between major versions. Running it on a v1 installation moves every installed integration to the current v2 release. If you defined custom rules under v1’s inline configuration, complete the legacy migration. Then confirm that the runtime is ready with npx cc-safety-net doctor. If you installed rulebooks from GitHub on 2.2 or earlier, run rule sync once per scope after upgrading, adding --global for user-scope sources. Rulebooks are now live vendored files instead of lock-and-cache state, and the command migrates each cached rulebook into the live path its source loads from, then removes the leftovers. Until it runs, those GitHub-sourced rules are inactive and status and doctor report the degraded sources.

​
Install a specific agent

For scripted, non-interactive installs, pass exactly one target flag. Passing zero or more than one target flag is an error. In an interactive terminal, passing no target flag starts the installer selector. Every install command is idempotent: running it again on an already-configured agent is safe and leaves a single managed entry behind.

​
Amp Code installation

This publishes the managed plugin artifact to your account’s hosted Amp Personal Plugins repository. The artifact is a directory named cc-safety-net holding index.ts, the entry file Amp loads. A personal plugin follows your account everywhere, so it also covers threads that execute on a remote machine, such as Amp Orbs. Install requires the amp CLI and a signed-in account. It first runs amp plugins repositories --json to find your writable Personal Plugins repository. If the CLI or login is missing, install stops and points you to amp login. It then clones user-plugins into a temporary checkout, writes cc-safety-net/index.ts, commits under the tool identity cc-safety-net, and pushes. Staging names that one file (git add -- cc-safety-net/index.ts) instead of the directory. If your repository gitignores that path, git add fails and the install stops, instead of staging nothing and reporting the plugin as already installed. Commit signing is off, so your global git config cannot stall the install. Run the command again to update the published artifact in place. Earlier releases published a single file cc-safety-net.ts at the root of that repository. Install migrates away from it. A managed legacy file goes in the same commit; an unmanaged one fails the install. Install also embeds a snapshot of your user policy file into the published artifact. At runtime, the snapshot applies only on a machine that has no policy file, such as an Orb’s empty home directory. A policy file on the machine always wins, even when it is invalid. If your policy file is absent or cannot be parsed, install publishes the bare artifact without a snapshot. The snapshot does not carry audit retention, user rulebooks, or project-scope policy. A policy edit ships on the next install --amp or update.
Uninstall removes cc-safety-net/index.ts from the personal repository with the same commit-and-push flow, together with a managed legacy cc-safety-net.ts at the root. Uninstall removes only that entry file, so anything else you keep in the cc-safety-net directory stays. It leaves anything else at the legacy root path untouched: an unmanaged file, a symlink, or a directory. It reports the cc-safety-net directory as the removed path, or the legacy root file when that was all it found.
Restart Amp or run plugins: reload after installing, updating, or uninstalling so the change takes effect.
Install and uninstall both refuse to touch a plugin in the personal repository that is not theirs to replace. They refuse a cc-safety-net entry that is a symlink or is not a directory. They refuse an index.ts inside it that is a symlink, is not a regular file, or does not carry the CC Safety Net managed header. Remove the entry there and rerun the command. Earlier releases copied the plugin to a local file at ~/.config/amp/plugins/cc-safety-net.ts. The plugin directory can also be copied to ~/.config/amp/plugins/cc-safety-net/ by hand. Either one masks the personal plugin, so install removes it after publishing: the legacy file when it is a managed copy, and the local directory when it holds nothing but a managed index.ts. Any other local entry at those two paths fails the install:
Uninstall also removes managed local copies but leaves an unmanaged local entry in place.

​
Antigravity CLI installation

This writes a managed PreToolUse entry to ~/.gemini/config/hooks.json that runs npx -y cc-safety-net hook --agy-cli on each run_command tool call. Because the hook runs through npx, install first deletes any cached cc-safety-net copies from the npm cache’s _npx directory ($npm_config_cache if set, otherwise ~/.npm on macOS and Linux, %LOCALAPPDATA%\npm-cache on Windows) so the hook resolves the current release. Uninstall does not touch the cache.
Optionally install the /cc-safety-net skill so you can author rules interactively inside Antigravity CLI:

​
Claude Code installation

This adds the cc-marketplace marketplace from kenryu42/cc-marketplace and installs the cc-safety-net@cc-marketplace plugin, enabling it if a disabled copy is already present.
Enable auto-updates To keep CC Safety Net up to date automatically, run /plugin inside Claude Code, navigate to Marketplaces, select cc-marketplace, and enable auto-update.
The plugin invokes the Coding CLI hook, cc-safety-net hook --coding-cli (short flag -cc). That is the canonical flag name. hook --claude-code is accepted only as a legacy alias. Do not use it in new configuration.

​
Codex installation

This adds the cc-marketplace marketplace from kenryu42/cc-marketplace and installs the cc-safety-net@cc-marketplace plugin. Codex support has one known enforcement bound: input typed into an already-running interactive session is never inspected or audited. See the Codex coverage boundary. Trust the hook Codex will not run an untrusted hook. Start Codex, open /hooks, select the cc-safety-net PreToolUse hook, and press t to trust it.
The plugin is packaged in Codex’s own format. Its hook runs cc-safety-net hook --codex (short flag -cx), and the same plugin carries the cc-safety-net skill.

​
Cursor installation

This writes a managed preToolUse entry to your global Cursor hooks config, ~/.cursor/hooks.json:
Because the config is global, this protects Cursor IDE and Cursor CLI sessions across all your projects. failClosed means Cursor denies the tool call if the hook cannot produce a decision. Because the hook runs through npx, install first clears cached cc-safety-net copies from the npm _npx cache so the hook resolves the current release; uninstall does not touch the cache. The cache locations are listed in the Antigravity CLI section.

​
Gemini CLI installation

This installs the Gemini Safety Net extension from https://github.com/kenryu42/gemini-safety-net, or re-enables it if a disabled copy is already present. Gemini CLI is not a cc-marketplace plugin. Its extension lives in its own repository under the extension id gemini-safety-net.
Restart Gemini CLI (or start a new session) after installing so the extension and its hook are loaded.

​
GitHub Copilot CLI installation

This adds the cc-marketplace marketplace if it is not already registered, installs the cc-safety-net@cc-marketplace plugin, and flips the plugin to true in enabledPlugins in ~/.copilot/settings.json if it was explicitly disabled.
Restart Copilot CLI after installing or removing the plugin for the change to take effect.
Hook support in Copilot CLI depends on its version. Doctor checks repository hook files under .github/hooks; inline hook definitions in .github/copilot/settings.local.json, .github/copilot/settings.json, .claude/settings.local.json, .claude/settings.json, ~/.copilot/settings.json, and ~/.copilot/config.json; and user hook files under ~/.copilot/hooks. Inline hook definitions require Copilot CLI 1.0.8 or later, and user hook files require 0.0.422 or later. The plugin handles this for you. If you configure hooks manually and find a problem, run npx cc-safety-net doctor. It reports the detected Copilot version and the supported hook sources.

​
Grok Build installation

This writes a managed PreToolUse entry to ~/.grok/hooks/cc-safety-net.json, or to $GROK_HOME/hooks/cc-safety-net.json when GROK_HOME is set:
The entry carries no matcher, so every tool call reaches the adapter instead of only run_terminal_command. The adapter also inspects the inputs of file and patch tools for protected paths. Because the hook runs through npx, install first clears cached cc-safety-net copies from the npm _npx cache so the hook resolves the current release; uninstall does not touch the cache. The cache locations are listed in the Antigravity CLI section.
Both commands only ever touch the managed handler. Install strips managed handlers out of the existing entries and appends the canonical entry standalone, so foreign entries, foreign handlers that shared an entry with it, and other hook events all survive. Uninstall removes the managed handler, drops an entry once it has no handlers left, and deletes the file only when nothing else remains in it. Uninstall leaves an unparsable file alone; install repairs one to the canonical entry, because Grok Build skips an unparsable hook file entirely, so such a file cannot carry working hooks anyway.
Grok Build hooks are fail-open and the host exposes no failClosed knob. Only an explicit deny blocks a tool call. A hook that crashes, times out, or emits malformed output lets the call proceed.

​
Hermes Agent installation

This writes the managed Python plugin files __init__.py and plugin.yaml to $HERMES_HOME/plugins/cc-safety-net/ (~/.hermes/plugins/cc-safety-net/ when HERMES_HOME is unset). It then runs hermes plugins enable cc-safety-net --no-allow-tool-override. The files alone are inert. Hermes loads a user plugin only when its own config lists it as enabled, so install runs the enable command even when the files are already current. Because the plugin shells out through npx, install first clears cached cc-safety-net copies from the npm _npx cache so the plugin resolves the current release; uninstall does not touch the cache. The cache locations are listed in the Antigravity CLI section.
Restart Hermes after installing, updating, or uninstalling so the change takes effect.
On each pre_tool_call, the plugin sends the tool call to npx -y cc-safety-net hook --hermes-agent (short flag -ha) over JSON stdin, with a 30-second timeout. It protects the terminal, read_file, write_file, and patch tools; other Hermes tools are not forwarded. The plugin fails closed: when npx is missing, the analysis cannot start, times out, exits non-zero, or returns unreadable output, the tool call is blocked with an explicit message instead of slipping through.
Uninstall runs hermes plugins disable cc-safety-net before it removes the plugin files. Hermes resolves only plugins that are still on disk. An enabled config entry would automatically load any future plugin with the same name. If the hermes CLI fails or is missing, uninstall still removes the files and warns that the Hermes config may still list cc-safety-net. Uninstall also removes the Python __pycache__ bytecode directory and reclaims the plugin directory only when nothing else remains. Install and uninstall both refuse to touch the plugin directory if it is a symlink or not a regular directory, and refuse to overwrite or remove any managed file that is a symlink, not a regular file, or does not carry the CC Safety Net managed header. Move or remove it yourself and rerun the command. This integration is macOS and Linux only.

​
Kimi Code installation

Kimi Code supports two install methods: a global hook written to your Kimi Code config, or a native Kimi Code plugin you install from inside Kimi Code. In an interactive terminal, install --kimi-code (or picking Kimi Code in the interactive installer) opens a single-select prompt asking which method to use: install the global hook now, or print the native-plugin steps. In a non-interactive session the flag installs the global hook directly, so scripts and CI pipelines never hang on a prompt. update is unchanged.
Kimi Code hooks are fail-open with either method: when the hook process cannot start, crashes, or times out, Kimi Code allows the tool call.
Global hook
This writes a [[hooks]] block to ~/.kimi-code/config.toml (or $KIMI_CODE_HOME/config.toml) that runs npx -y cc-safety-net hook --kimi-code on each PreToolUse call. The adapter treats Bash as a shell-command tool and inspects other tool inputs for protected paths. Because the hook runs through npx, install first clears cached cc-safety-net copies from the npm _npx cache so the hook resolves the current release; uninstall does not touch the cache. The cache locations are listed in the Antigravity CLI section.
Native plugin To use the native plugin instead, run this inside Kimi Code:
Confirm the trust prompt, which defaults to cancel. Then run /reload or start a new session. The plugin declares one PreToolUse hook with no tool matcher. It runs node ./dist/bin/cc-safety-net.js hook --kimi-code for every tool call with a 30-second timeout and uses the same adapter as the global hook. When the global hook is already configured, the Kimi Code row in the interactive installer stays selectable and is labeled (global hook installed), and the printed plugin steps add a caution: run cc-safety-net uninstall --kimi-code only after the plugin is active. A brief overlap where both hooks run just duplicates the denial message, while a gap with neither active leaves you unprotected. Optionally install the /cc-safety-net skill so you can author rules interactively inside Kimi Code:

​
OpenClaw installation

This installs the plugin through OpenClaw’s own CLI: it runs openclaw plugins install <packaged plugin dir> --force followed by openclaw plugins enable cc-safety-net, where the packaged plugin directory ships inside the npm package. It then verifies the plugin actually loaded by running openclaw plugins inspect cc-safety-net --runtime --json: an enabled plugin whose runtime is broken installs cleanly and then silently protects nothing, so anything other than a loaded status fails the install and points you at openclaw plugins inspect cc-safety-net --runtime for details. Because --force overwrites the entry with the cc-safety-net extension id and uninstall deletes that entry, both commands first inspect the extension directory. They continue only if the directory contains only a managed CC Safety Net plugin or is empty. Otherwise, they refuse to run. Move or remove the directory and run the command again.
Restart the OpenClaw Gateway after installing, updating, or uninstalling so the change takes effect. If plugins.allow is set in openclaw.json, it must also list cc-safety-net. An allowlist that omits it prevents the plugin from loading even when it is enabled.
OpenClaw loads CC Safety Net as an in-process plugin rather than a hook subprocess, so there is no runtime hook flag. The plugin registers a before_tool_call handler for the untagged exec tool only. OpenClaw’s file tools and tagged exec variants are not covered. Each supported exec call is analyzed against the agent’s workspace directory, and the plugin fails closed when that workspace cannot be resolved, when workdir resolves outside it, or when the call names an execution host other than auto or gateway (for example sandbox or node). OpenClaw’s state directory is OPENCLAW_STATE_DIR when set, otherwise the directory holding OPENCLAW_CONFIG_PATH, otherwise ~/.openclaw; the config file is OPENCLAW_CONFIG_PATH when set, otherwise openclaw.json in the state directory. A leading ~ path in either environment variable expands against the user’s home directory. Install and doctor resolve paths in that same order, so a relocated OpenClaw install is handled instead of reported as absent. This integration is macOS and Linux only.

​
OpenCode installation

OpenCode uses $XDG_CACHE_HOME/opencode as its cache directory when XDG_CACHE_HOME is set and non-empty, otherwise ~/.cache/opencode. It can keep serving a stale cached plugin version, so the install command clears packages/cc-safety-net@latest under that directory before running opencode plugin -g -f cc-safety-net@latest. Install then proves that the cached package exists, its declared main entry loads, and it exports a callable CCSafetyNetPlugin; a failed proof stops the install because OpenCode would otherwise continue without protection.
OpenCode uses $XDG_CONFIG_HOME/opencode as its config directory when XDG_CONFIG_HOME is set and non-empty, otherwise ~/.config/opencode. Uninstall removes cc-safety-net from the plugin array in opencode.json or opencode.jsonc there and clears the cached package again. Restart OpenCode after installing or updating so the plugin is loaded from the refreshed cache.

​
Pi installation

This runs pi install npm:cc-safety-net and, if your Pi settings pin an extensions filter that would leave CC Safety Net disabled, clears that filter in ~/.pi/agent/settings.json.
Pi loads CC Safety Net as an in-process extension rather than a hook subprocess. The extension analyzes only Pi’s built-in bash tool as a shell command. It also inspects other tool inputs for protected paths, but it does not support custom command tools named Shell (for example pi-grok-cli). It registers a /cc-safety-net builtin command for managing rulebooks. See Integration architecture for details.

​
Migrating from a legacy plugin identifier

The current plugin identifier is cc-safety-net@cc-marketplace everywhere it applies. Two identifiers from earlier releases still show up on existing machines: You do not need to remove these by hand. Run the normal install command for the agent, and it will migrate the identifier. Do not use the legacy identifiers in new configuration.

​
Verify your installation

After installing, run the doctor command to confirm CC Safety Net is wired up correctly and blocking commands as expected:
doctor runs a full health check across every supported agent. It checks hook integration, runs a self-test that confirms blocking works, validates custom rules, and checks active mode flags, recent activity, system versions, and updates. See the doctor command reference for details and available flags. If any check fails, the output includes a description of the problem and suggested fixes.
Last modified on September 15, 2026