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
/plugin marketplace add karanb192/claude-code-hooks
/plugin install config-watch@claude-code-hooksWhat 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.jsonduring a session - stop an npm postinstall from changing settings mid-run
- see which source triggered a config change
- read the raw
ConfigChangepayload 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=trueand restart the session. - Show me the
ConfigChangeevents 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-hooksStep 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