Troubleshooting installation and behavior

Run npx cc-safety-net status for the verdict, then npx cc-safety-net doctor for the full report. Most problems show up there. Then find your symptom below.

Run diagnostics first

npx cc-safety-net status
npx cc-safety-net doctor

status prints ready or degraded, the active protections, and one line per open issue. doctor checks every agent’s integration, runs a blocking self-test, validates your rules and policy.json, and checks for updates. See status and doctor.

Commands run without being checked

A command that should be blocked runs with no message. The integration for your agent is missing, disabled, or not loaded.

Run doctor

npx cc-safety-net doctor reports each agent’s integration and names the config file it read.

Run the install again

Re-run the install command for your agent from Install for one agent. It repairs a missing or disabled managed entry. If it reports a config or file it does not recognize, follow its message instead of overwriting the file.

Check the agent-specific cause

Use the table below.

Restart the agent

Reload or restart your agent session after any change.

Agent	What to check
Amp Code	`amp plugins list` shows the plugin as `active`
Antigravity CLI	`~/.gemini/config/hooks.json` parses and holds the managed entry
Claude Code	`/plugin` lists `cc-safety-net` as enabled
Codex	You trusted the hook in `/hooks`
Cursor	`~/.cursor/hooks.json` parses and holds the managed entry
DeepSeek Harness	Each profile’s `dsh.profile.bundles` includes `cc-safety-net`
Devin CLI	`config.json` parses and holds the managed entry
Factory Droid	`allowManagedHooksOnly` is off
Gemini CLI	`gemini extensions list` shows `gemini-safety-net` enabled
GitHub Copilot CLI	The plugin switch and `disableAllHooks`
Grok Build	The hook is not listed in `disabled-hooks`
Hermes Agent	The plugin is enabled and Hermes was restarted
Kimi Code	No `[[hooks]]` entry is invalid, and the native plugin is enabled
OpenClaw	The plugin is `loaded`, `plugins.allow` lists it, and the Gateway was restarted
OpenCode	OpenCode does not report the plugin as failed
Pi	No `extensions` filter hides the extension, and Pi was restarted

Every command waits seconds before it runs

A healthy check finishes in well under a second. A delay of seconds comes from npx resolving the package, not from the analysis. The Antigravity CLI, Cursor, Devin CLI, Factory Droid, Grok Build, Hermes Agent, and Kimi Code global hook run npx -y cc-safety-net on every call. The Claude Code plugin runs a bundled copy, so this does not apply there.

time npx -y cc-safety-net --version
time npx -y --prefer-offline cc-safety-net --version
npm cache verify

Warm runs of the first command should take a few hundred milliseconds. If only the --prefer-offline run is fast, npx is waiting on the npm registry, which is a network or proxy problem. Otherwise npm cache verify repairs a bloated or corrupt npm cache.

A destructive command ran without a block

Most cases are a documented allowance or a lower safety level than you assumed. Check these in order:

Run npx cc-safety-net explain "<the command>". It shows the rules checked, the effective safety level, and any rule that is off at that level.
If the level is standard, the command may be a standard relaxation. Use strict or paranoid if commands may be adversarial.
In Claude Code, you may have approved it. See When Claude Code asks you instead of blocking.
The command may be allowed on purpose, such as rm -rf inside the working directory. See Blocked commands.
npx cc-safety-net status reads degraded when CC Safety Net has dropped a rule source, which turns off that source’s denials. See Configuration recovery.
A Project policy block in status lists what a project policy.json relaxed in this project. See Reported weakenings.
The command ran through a proxy that CC Safety Net does not unwrap. Declare the proxy with npx -y cc-safety-net rule wrapper add <command>.
Your agent may not cover that tool or directory. See Agent-specific limits.

If none of these explains it, report a coverage gap as a public GitHub issue. Describe the command shape, not a working payload. To block it now, add a custom rule.

A command you need is blocked

The message names the rule. Run npx cc-safety-net explain "<the command>" to see why it matched, then use Allow a blocked command to turn the rule off or allow a path. Other options:

In a linked git worktree, turn on worktree mode to relax the local-discard rules.
Use a safer variant. git push --force-with-lease and git clean -n are allowed.
Run the command yourself outside the agent.

Denial messages

Each entry quotes the message the agent receives. Every id is listed in Fixed denial ids.

The command exceeds the derived-command work limit

Command analysis exceeds CC Safety Net's derived-command work limit. Reduce nested or embedded command complexity and retry.

No rule matched. The command nests too many derived commands, such as shell one-liners inside find -exec, xargs, or wrappers. No setting raises the limit. Split it into simpler commands.

The command exceeds safe analysis limits

CC Safety Net could not analyze the command because it exceeds safe analysis limits. Simplify or split the command and retry.

No rule matched. The command has too many paths, shell functions, or nested heredocs to analyze. No setting raises the limit. Simplify or split it.

Analysis failed unexpectedly

CC Safety Net failed closed because command analysis failed unexpectedly. This is not caused by your command. Report it to the user.

An internal fault, not your command, caused the block. Changing the command is not the fix. Report it with the steps in Collect diagnostics and report the issue.

The tool call arrived malformed

CC Safety Net could not check this tool call because it arrived without a usable tool name or arguments. This is not a CC Safety Net failure. Send the call again with its tool name and complete arguments.

The agent sent a call with no tool name, a blank command, or a blank working directory argument, so there was nothing to check. The id is tool-call.malformed. The agent can send the call again with complete arguments. There is nothing to report.

The session’s working directory is unusable

CC Safety Net cannot check tool calls because the session's working directory or workspace root no longer exists, is inaccessible, is not a directory, or uses an unsupported path form. Ask the user to restart the session from an existing directory.

CC Safety Net denies every call because the directory the session started in is gone. A deleted git worktree is a common cause. A session directory outside the workspace roots gets a similar message. Restart the agent from a directory that exists inside the workspace.

The denial names the requested working directory

CC Safety Net could not use the requested working directory because it does not exist, is inaccessible, is not a directory, or uses an unsupported path form. Use an existing accessible working directory. If the requested directory is missing, create it from an accessible location before retrying the command.

One call asked to run in a directory CC Safety Net could not use, such as an Amp Code dir, an OpenCode workdir, or a Kimi Code cwd. A variant says the directory is outside the session’s workspace. The session keeps working. Point the call at an existing directory inside the workspace, or create the missing one first, and retry. The agent’s page lists how it resolves working directories.

Claude Code asks “could not verify this command”

The prompt is headed CC Safety Net could not verify this command rather than BLOCKED by CC Safety Net. Nothing was blocked yet. Approving the prompt runs the command. See When Claude Code asks you instead of blocking.

Only the user may apply a policy proposal

Only the user may apply a policy proposal, because it rewrites the configuration CC Safety Net enforces. Ask them to run `cc-safety-net policy apply <file>` themselves in a terminal; you can run `cc-safety-net policy check <file>` to show them what it would change.

The agent tried to run policy apply, which has no override. Run npx cc-safety-net policy apply <file> yourself in a terminal. See Agents cannot run policy apply.

Custom rules are not enforced

CC Safety Net drops a rule source that fails validation, and status reads degraded. Your commands keep running, but that source’s rules stop applying.

Run npx cc-safety-net doctor. It names the rejected file and the reason.
Run npx -y cc-safety-net rule list to see which sources and rulebooks each scope loaded. An edit to a rulebook under another name has no effect, and an overrides entry in rule.json can turn a rule off.
Run npx -y cc-safety-net rule verify after each fix. It fails with the remaining error rather than reporting success.
If you used the legacy .safety-net.json or ~/.cc-safety-net/config.json, run npx -y cc-safety-net rule migrate. doctor reports an unmigrated file as config.legacy-ignored.

File locations are in Where configuration lives, and every failure is in Configuration recovery.

policy or rule commands say the path is the user config

<home>/.cc-safety-net/policy.json is the user policy, not a project policy; use --global for the user scope, or run from a project directory

You ran a project-scope policy or writing rule command from the directory that holds your user .cc-safety-net/, usually your home directory. The rule commands print the same message for rule.json. Add --global for the user scope, or change into the project directory. See Which file policy writes.

status reports degraded

CC Safety Net rejected a configuration file and put a fallback in force. It never denies ordinary work for this reason.

Run npx cc-safety-net doctor. The config.runtime-degraded finding names the file and the fix.
Fix that file, or run npx -y cc-safety-net rule update to vendor a missing remote source, then npx -y cc-safety-net rule verify.
Fix policy.json by hand. Most rejected sections fall back to stricter defaults, but an invalid safety.level falls back to standard and lowers your protection.

See Configuration recovery.

doctor reports rulebook lock and cache leftovers

The config.v2-leftovers finding is informational, and every rule keeps enforcing. Run npx -y cc-safety-net rule sync, adding --global for the user scope, to migrate and remove the files. See rule sync.

The status line does not show in Claude Code

Check that ~/.claude/settings.json has the statusLine entry from Set up the Claude Code status line. Then run its command, such as npx -y cc-safety-net statusline --claude-code, in a terminal. If it fails there, the status line stays blank.

An update did not take effect

npx -y cc-safety-net@latest update

update refreshes every installed integration. Keep @latest, because a bare cc-safety-net can run an older cached copy. Check the result with npx cc-safety-net --version. For Claude Code, you can also turn on auto-updates. See update.

Collect diagnostics and report the issue

npx cc-safety-net doctor --json

The JSON output captures your environment, versions, hook configuration, and self-test results. It contains absolute paths and project names, so read Before you share a trace before you paste it. Choose a public or private report says where to file it.

Get started

Guides

Configuration