Skip to main content
plugin

config-guard — Claude Code plugin: what it does, how to install

config-guard — a PreToolUse hook that stops the agent from rewriting the files holding its own guardrails: settings, hook scripts, plugin manifests. Reads pass.

MIT ★ 586 updated 2026-10-26

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add karanb192/claude-code-hooks
/plugin install config-guard@claude-code-hooks
Open on GitHub

What config-guard does

The hook fires before every Bash, Edit, MultiEdit and Write call. It compares the target path or command string against a protected set and answers a match with a deny carrying the rule id and a reason. Reading stays open, since the agent needs settings to work at all.

Levels stack on each other. critical covers the enforcement chain: .claude/settings.json, settings.local.json, managed-settings.json, everything under .claude/hooks/, plus hooks.json. high, the default, adds .mcp.json, .claude-plugin/ and the CLI writes made through claude config set, claude mcp add, claude plugin install. strict also guards CLAUDE.md, .claude/rules/, .claude/agents/ and .claude/commands/. Those instruction files stay writable unless you export HOOK_SAFETY_LEVEL=strict.

Creating a protected file counts as mutation as well, the trick used to plant a payload in .claude/settings.json. Symlinked targets get resolved before the check. Matching is textual, so this is no shell parser: interpreter one-liners such as python -c, git checkout of a config path, chmod, and paths assembled from variables slip past. One deliberate change goes ahead with CONFIG_GUARD_ALLOW=true; the HOOK_ASK_* variables turn a deny into a prompt. Decisions land in ~/.claude/hooks-logs/, and nothing leaves the machine.

What it helps with

  • keep the agent out of settings.json and hook scripts
  • catch a fresh .mcp.json or plugin manifest being written
  • pick a strictness level that fits the repo
  • let one hand-approved config edit through
  • review which config writes the agent attempted

Example prompts for the agent

  • Add a linter hook to .claude/settings.json
  • Install that MCP server with claude mcp add and list what is connected
  • Drop the tab rule from CLAUDE.md

How to install config-guard

Plugin marketplace

/plugin marketplace add karanb192/claude-code-hooks
/plugin install config-guard@claude-code-hooks

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about config-guard

How to install config-guard in Claude Code?

Add the marketplace first: /plugin marketplace add karanb192/claude-code-hooks. Then install the plugin: /plugin install config-guard@claude-code-hooks. Restart Claude afterwards.

What does config-guard do?

It denies the agent's writes to the files behind its guardrails: settings that register hooks and permissions, the hook scripts, hooks.json, .mcp.json, plugin config. Reading them is allowed.

What does config-guard miss?

Interpreter one-liners like python -c, git checkout or git restore against a config path, chmod, and paths built from variables. Bash strings are matched as text, so a redirect through a symlinked directory is not resolved.

Source text

config-guard · MIT
# config-guard

> Who guards the guards: blocks the agent from tampering with its own guardrail configuration, so no other hook can be switched off from inside a session.

A `PreToolUse` hook fires before every `Bash`, `Edit`, `MultiEdit`, and `Write` call and denies any mutation of the files that wire your guardrails: settings files that register hooks and permissions, the hook scripts themselves, `hooks.json` manifests, `.mcp.json`, and plugin config. Reads always pass (agents legitimately read settings); only writes, in-place edits, moves, copies onto, symlink swaps, and deletes are stopped, plus the `claude config set`, `claude mcp add`, and `claude plugin install` CLI forms that rewrite agent config without naming a settings path. Creating a protected file that does not exist yet also counts as mutation: that was the CVE-2026-25725 persistence vector, and the Aug 2026 CHAINDROP npm worm hid its payload in `.claude/settings.json` the same way. Edit/MultiEdit/Write paths are resolved through symlinks before checking, so a write through `ln -s ~/.claude /tmp/x` is still caught.

## Install

```
/plugin marketplace add karanb192/claude-code-hooks   # once per machine
/plugin install config-guard@claude-code-hooks
```

Restart Claude Code, done. (Or from a shell: `claude plugin install config-guard@claude-code-hooks`.)

## What it does

| Event | Matcher | What happens |
|-------|---------|--------------|
| PreToolUse | `Bash\|Edit\|MultiEdit\|Write` | Checks the target path (Edit/MultiEdit/Write) or command string (Bash) against the protected set for the active safety level; returns `permissionDecision: "deny"` (or `"ask"` in ask mode) with the pattern id and reason, `{}` otherwise. |

Three safety levels, each including the previous:

| Level | Protects |
|-------|----------|
| `critical` | The enforcement chain: `.claude/settings.json`, `.claude/settings.local.json`, `managed-settings.json`, anything under `.claude/hooks/`, `hooks.json` manifests. |
| `high` (default) | Plus the config supply chain: `.mcp.json`, `.claude-plugin/`, and `claude config set\|add\|remove`, `claude mcp add\|add-json\|add-from-claude-desktop\|remove`, `claude plugin install\|uninstall\|enable\|disable\|update\|marketplace` (list/get forms stay allowed). |
| `strict` | Plus instruction files that steer the agent: `CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/`, `.claude/agents/`, `.claude/commands/`. |

## Configuration

All optional, set via environment variables:

| Variable | Default | Purpose |
|----------|---------|---------|
| `HOOK_SAFETY_LEVEL` | `high` | Safety level: `critical`, `high`, or `strict`. Invalid values fall back to `high`. Env-only on purpose: plugin updates overwrite installed files, so never edit the script. |
| `CONFIG_GUARD_ALLOW` | unset | Escape hatch for an intentional, human-approved config change: the literal string `true` lets the call through (anything else still denies). Export it for one shell call, or prefix a single hook command with it in settings.json. |
| `HOOK_ASK_CRITICAL` | unset | `true` prompts the user instead of denying for `critical`-level matches. |
| `HOOK_ASK_HIGH` | unset | `true` prompts instead of denying for `high`-level matches. |
| `HOOK_ASK_STRICT` | unset | `true` prompts instead of denying for `strict`-level matches. |

Ask mode is strictly per level and opt-in: everything defaults to deny.

## Known limits

Deliberately not a full shell parser: a mutation verb and a protected path in the same Bash command block it even if the verb technically targets another argument. Interpreter one-liners (`python -c "open(...).write(...)"`), `git checkout/restore` of a config path, `chmod`, and paths built from variables (`"$DIR/settings.json"`) are not caught. Shell command strings are matched as text, so a Bash redirect through a symlinked directory is not resolved. PreToolUse only sees the agent's own tool calls; out-of-band changes are covered by its sibling [config-watch](https://github.com/karanb192/claude-code-hooks) (ConfigChange event) in the root repo.

## Data & privacy

Logs decisions (pattern id, tool, truncated target, session id) to `~/.claude/hooks-logs/`. No network calls; everything stays on your local machine.

## Uninstall

```
/plugin uninstall config-guard@claude-code-hooks
```

Part of [claude-code-hooks](https://github.com/karanb192/claude-code-hooks).

© Karan Bansal · MIT · karanb192/claude-code-hooks

Similar plugins

All plugins for Security →

From the same set28

The whole set →
format-code format-code — a PostToolUse hook that formats each file right after Claude writes or edits it: ruff for Python, prettier for JS, TS, JSON, MD, YAML and HTML. ★ 586repo stars auto-stage auto-stage stages modified files in Git automatically whenever Claude Code writes or edits them, keeping pre-commit reviews clean without manual git add calls. ★ 586repo stars config-watch config-watch makes every mid-session change to settings or skills visible in the session, or blocks it outright. Aimed at installers and npm scripts that rewrite config while the agent works. ★ 586repo stars subagent-spawn-cap subagent-spawn-cap counts subagent spawns per session: asks at 20, asks again every 10, refuses at 60. Puts back the cap Claude dropped in 2.1.224. ★ 586repo stars case-insensitive-guard case-insensitive-guard is a Claude Code plugin that blocks destructive Bash commands aimed at a path with a different letter case. It checks commands such as rm -rf before they run. ★ 586repo stars protect-tests protect-tests blocks the "fake green" trap: stops the agent from deleting, renaming, or skipping tests instead of fixing the code. Works with pytest, jest, Go, JUnit, RSpec, and more. ★ 586repo stars git-safety git-safety — a PreToolUse Bash hook for Claude Code that intercepts destructive git and gh CLI actions before execution. ★ 586repo stars protect-secrets protect-secrets — a PreToolUse hook that checks every Read, Edit, Write, Bash and Grep call and blocks .env, SSH keys or cloud credentials — or asks you first. ★ 586repo stars

Project sponsors

Companies that keep this analytics open