Skip to main content
plugin

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

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.

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-watch@claude-code-hooks
Open on GitHub

What config-watch does

The plugin registers a ConfigChange hook. Any time settings change mid-session (user, project, local or policy), or a skill file is touched, the hook fires. You get a systemMessage naming the source and, when the payload carries one, the file path. Default behaviour is warn only: exit 0, nothing stopped.

Set CONFIG_WATCH_BLOCK=true and the hook exits 2 instead, writing the reason to stderr so the edit never lands. Policy settings are the exception, because hooks cannot block those and they always warn. ConfigChange also fires for edits you make yourself through /config or your editor, which is why block mode is opt-in for hardened machines.

Since the event's payload schema is undocumented, the script reads it defensively: source, config_source or matcher, plus file_path or path. Every event lands in ~/.claude/hooks-logs/<date>.jsonl with the raw payload. The script touches nothing but fs and path, so no traffic leaves the machine. config-guard covers the agent's own writes; this one watches the outside path.

What it helps with

  • spot an installer rewriting .claude/settings.json during a session
  • stop an npm postinstall from changing settings mid-run
  • see which source triggered a config change
  • read the raw ConfigChange payload out of the log
  • watch outside edits while config-guard handles the agent's own writes

Example prompts for the agent

  • Turn on blocking: set CONFIG_WATCH_BLOCK=true and restart the session.
  • Show me the ConfigChange events logged in ~/.claude/hooks-logs/<date>.jsonl.
  • Work out who rewrote the settings and pull the raw payload from the hook log.

How to install config-watch

Plugin marketplace

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

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

Questions about config-watch

How do I install config-watch in Claude Code?

Run /plugin marketplace add karanb192/claude-code-hooks once, then /plugin install config-watch@claude-code-hooks. Restart Claude afterwards.

What does config-watch do?

It adds a ConfigChange hook that reports mid-session edits to settings or skills in a systemMessage, and stops them from taking effect when block mode is on.

Can policy settings be blocked?

No. Hooks cannot block policy_settings, so those changes still come through as warnings in either mode.

Source text

config-watch · MIT
# config-watch

> Tripwire for out-of-band config changes: makes every mid-session settings/skills change loudly visible, or blocks it outright.

A `ConfigChange` hook fires whenever a configuration file changes while a session runs: an installer script, an npm postinstall payload (the CHAINDROP worm hid in `.claude/settings.json` exactly this way), or any other process rewriting settings behind Claude Code's back. By default it emits a `systemMessage` naming the changed source (and file path when the payload includes one) so the change is visible in the session instead of sliding by silently. Opt into block mode and it exits 2 to stop the change from taking effect; `policy_settings` cannot be blocked by hooks per the docs, so those still warn.

Pairs with [config-guard](https://github.com/karanb192/claude-code-hooks): config-guard (PreToolUse) blocks the agent's own writes to its guardrail config; config-watch covers the out-of-band path.

One caveat, straight from the docs: the hooks reference guarantees ConfigChange can block via exit 2 but does not document the event's payload schema. The hook therefore parses defensively (accepts `source` / `config_source` / `matcher` and `file_path` / `path`) and logs the raw payload so you can inspect what your Claude Code version actually sends.

## Install

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

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

## What it does

| Event | Matcher | What happens |
|-------|---------|--------------|
| ConfigChange | `user_settings\|project_settings\|local_settings\|policy_settings\|skills` | Warn mode (default): emits a `systemMessage` naming the changed source, exit 0. Block mode: exits 2 with the reason on stderr, stopping the change from taking effect; `policy_settings` still warns. Either way, the raw payload is logged. |

Note: ConfigChange also fires for changes YOU make (e.g. `/config`, editing settings in your editor), so block mode is opt-in for hardened setups; the default keeps legitimate workflows friction-free.

## Configuration

Optional, set via environment variable:

| Variable | Default | Purpose |
|----------|---------|---------|
| `CONFIG_WATCH_BLOCK` | `false` | Set to the literal string `true` to block config changes (exit 2) instead of warning. Any other value keeps warn mode. `policy_settings` cannot be blocked and always warns. |

## Data & privacy

Logs each event (including the raw payload, since the schema is undocumented) to `~/.claude/hooks-logs/<date>.jsonl`. It makes no network calls (the script only uses `fs` and `path`), so everything stays on your local machine.

## Uninstall

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

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

Similar plugins

All plugins for Security →

From the same set28

The whole set →
notify-permission notify-permission sends Slack cards when Claude Code waits for permissions or user input, freeing you from watching long-running terminal tasks. ★ 586repo stars session-logger session-logger is a Claude Code plugin that keeps a Markdown record of each session. Its hooks track the repository, touched file paths, and Bash commands. ★ 586repo stars 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 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 config-guard config-guard — a PreToolUse hook that stops the agent from rewriting the files holding its own guardrails: settings, hook scripts, plugin manifests. Reads pass. ★ 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

Project sponsors

Companies that keep this analytics open