> ## Documentation Index
> Fetch the complete documentation index at: https://ccsafetynet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting CC Safety Net Installation and Behavior

> Fix common CC Safety Net issues: hook not firing, commands not blocked, false positives, custom rules not loading, and status line not showing.

This guide covers the most common issues with CC Safety Net and how to resolve them. Start with the `doctor` command — it automates most diagnostics and will catch the majority of configuration problems in one pass.

## Run Diagnostics First

```bash theme={"dark"}
npx cc-safety-net doctor
bunx cc-safety-net doctor
```

`doctor` runs a comprehensive health check across every supported agent — hook integration, a self-test that confirms blocking works, custom-rule validation, active mode flags, recent activity, system versions, and an update check. See the [doctor command reference](/docs/reference/cli-commands#doctor) for what each check does.

Review the output before diving into the individual issues below. Most problems are visible here.

## Common Issues

<AccordionGroup>
  <Accordion title="Hook not firing — commands execute without being checked">
    If you run a command that should be blocked and it executes without any intervention, the hook is not registered correctly for your agent.

    **Steps to resolve:**

    1. Run `npx cc-safety-net doctor` — it checks hook integration for every supported agent and flags misconfiguration with the exact config path.
    2. **Claude Code**: run `/plugin` inside Claude Code and confirm that `safety-net` appears in the installed plugins list and is enabled. If it doesn't appear, reinstall with `/plugin install safety-net@cc-marketplace`, then `/reload-plugins`.
    3. **Codex**: open your `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and verify that `plugin_hooks = true` is set under `[features]` and `enabled = true` is set under `[plugins."safety-net@cc-marketplace"]`. Then run `/hooks` in the TUI, select the safety-net PreToolUse hook, and press `t` to mark it as trusted. Without the trust step, the hook will not fire.
    4. **Gemini CLI**: run `gemini extensions list` and confirm the `https://github.com/kenryu42/gemini-safety-net` source is installed and enabled (check both User and Workspace scope — Workspace wins if set). Reinstall with `gemini extensions install https://github.com/kenryu42/gemini-safety-net` and start a new Gemini session.
    5. **Copilot CLI**: confirm the `copilot-safety-net` plugin is installed (`/plugin`), and that hooks are not disabled via `disableAllHooks: true` in `~/.copilot/config.json`, `.github/copilot/settings.json`, or `.github/copilot/settings.local.json`. Inline hooks require Copilot CLI 1.0.8+ and user hook files require 0.0.422+.
    6. **Kimi Code**: check `~/.kimi-code/config.toml` (or `$KIMI_CODE_HOME/config.toml`) for a `[[hooks]]` block running `npx -y cc-safety-net hook --kimi-code` on `PreToolUse` `Bash`. Re-run `npx -y cc-safety-net hook install --kimi-code` if it's missing.
    7. **OpenCode**: check `~/.config/opencode/opencode.json` (or `.jsonc`) for `cc-safety-net` in the `plugin[]` array. OpenCode can cache a stale version — see the [Installation](/docs/installation#opencode) cache-clearance steps.
    8. **Pi**: confirm `pi install npm:cc-safety-net` completed and you restarted Pi so the extension loads. Pi runs CC Safety Net as an in-process extension; run `npx cc-safety-net doctor` which probes Pi directly.
    9. After making any changes, reload or restart your agent session.
  </Accordion>

  <Accordion title="A destructive command wasn't blocked">
    If a command you expected to be blocked was allowed through, there are a few possible explanations.

    **Steps to resolve:**

    1. Run `npx cc-safety-net explain "<the command>"` to see the full step-by-step analysis of how CC Safety Net evaluated that specific command. This will show you exactly which rules were checked and why the command was allowed.
    2. The command may fall into an explicitly allowed category. For example, `rm -rf` within the current working directory is allowed by default because it's scoped to your project. See the [Commands Allowed](/docs/reference/allowed-commands) reference for the full list.
    3. If you need the command blocked in your context, create a custom rulebook with `npx -y cc-safety-net rule init` and add a rule to `.cc-safety-net/rules/project-rules/rulebook.json`. See [Custom Rules](/docs/configuration/custom-rules) for the schema.
    4. If you believe the command should have been blocked by a built-in rule and wasn't, share the output of `npx cc-safety-net doctor --json` when filing a bug report.
  </Accordion>

  <Accordion title="CC Safety Net is blocking a command I need">
    Built-in rules are conservative by design. If a command you need is being blocked, you have several options.

    **Steps to resolve:**

    1. Run `npx cc-safety-net explain "<the command>"` to understand exactly why it's being blocked and which rule matched.
    2. Consider these alternatives depending on your situation:
       * **Working in a linked git worktree?** Set `CC_SAFETY_NET_WORKTREE=1`. This relaxes local-discard rules when the command is proven to run inside a linked worktree, which is designed to be a disposable, isolated workspace.
       * **Need a safer variant?** For example, `git push --force-with-lease` is allowed and provides the same outcome as `--force` with an added safety check. `git clean -n` (dry-run) is allowed and lets you preview what would be removed.
       * **Command is genuinely needed?** Run it manually outside the agent. This is always an option, and CC Safety Net will tell the agent to ask you to do exactly this when a block fires.
    3. If none of the above apply, you can add a custom allow path by structuring the situation so the agent asks you to run the command directly.
  </Accordion>

  <Accordion title="Custom rules not loading">
    Rulebook-backed custom rules **fail closed** when configured rulebooks cannot be loaded safely. If your rulebook has any problem, commands stay blocked until it's fixed.

    **Steps to resolve:**

    1. Run `npx -y cc-safety-net rule verify` to validate rulebook structure, and `npx -y cc-safety-net rule test` to run every fixture. These commands surface the exact errors.
    2. Check that you're using the correct file locations:
       * **User scope**: `~/.cc-safety-net/rules/rule.json` (created with `rule init --global`)
       * **Project scope**: `.cc-safety-net/rules/rule.json` in your project root
    3. Ensure both `rule.json` and your rulebook JSON files are valid JSON. Common mistakes include trailing commas and unquoted keys.
    4. Confirm that `"version": 1` is present in `rule.json` and `"rulebook_version": 1` is present in each `rulebook.json`. Both fields are required.
    5. If you previously used the legacy inline config (`.safety-net.json` or `~/.cc-safety-net/config.json`), run `npx -y cc-safety-net rule migrate` to convert it to the new layout. Legacy files with rules cause commands to fail closed until migrated.
    6. After making changes to rulebook sources, run `npx -y cc-safety-net rule sync` to rebuild the lock and cache, then re-run `rule verify` and `rule test`.
  </Accordion>

  <Accordion title="Status line not showing in Claude Code">
    The status line requires an entry in `~/.claude/settings.json`. If it's not appearing, the entry is likely missing, malformed, or pointing to the wrong runtime.

    **Steps to resolve:**

    1. Open `~/.claude/settings.json` and verify the `statusLine` entry is present. It should look like one of the following:
       ```json theme={"dark"}
       { "statusLine": { "type": "command", "command": "bunx cc-safety-net statusline --claude-code" } }
       ```
       ```json theme={"dark"}
       { "statusLine": { "type": "command", "command": "npx -y cc-safety-net statusline --claude-code" } }
       ```
    2. Changes to this file take effect immediately — you do not need to restart Claude Code.
    3. If you're using the `claude x` variant, note that it is only compatible with the native version of Claude Code. If you installed Claude Code via npm, use `npx` or `bunx` instead.
    4. Test the status line command directly in your terminal to confirm it produces output:
       ```bash theme={"dark"}
       bunx cc-safety-net statusline --claude-code
       ```
       If this command fails, the status line will be blank inside Claude Code.
    5. Note that the status line reflects the `enabledPlugins["safety-net@cc-marketplace"]` entry in `~/.claude/settings.json`. If you run CC Safety Net as a manual hook or for another agent, it may show `❌` even though protection is active. See [Status Line](/docs/configuration/status-line) for what each indicator means.
  </Accordion>

  <Accordion title="Getting an update">
    CC Safety Net should be kept up to date to get the latest blocking rules and bug fixes.

    **Claude Code (plugin marketplace):**

    Go to `/plugin` → select `Marketplaces` → choose `cc-marketplace` → enable auto-update. Alternatively, re-run the install command to pull the latest version:

    ```bash theme={"dark"}
    /plugin install safety-net@cc-marketplace
    ```

    **npm / npx:**

    If you're invoking CC Safety Net via `npx`, use the `@latest` tag to always run the newest version:

    ```bash theme={"dark"}
    npx cc-safety-net@latest doctor
    ```

    If you have a local install, update it with your package manager.

    **Check your current version:**

    ```bash theme={"dark"}
    npx cc-safety-net --version
    ```
  </Accordion>
</AccordionGroup>

## Getting Help

If you're unable to resolve an issue with the steps above, collect the full diagnostic output before filing a report:

```bash theme={"dark"}
npx cc-safety-net doctor --json
```

The `--json` flag produces structured output that captures your environment, installed versions, hook configuration, and self-test results in a single snapshot. Include this output when [opening an issue on GitHub](https://github.com/kenryu42/cc-safety-net/issues).