config-watch — плагин для Claude Code: что делает и как установить
Плагин config-watch показывает в сессии любое изменение настроек или скиллов, случившееся посреди работы, либо блокирует его. Для случаев, когда установщик или npm-скрипт правит конфиг во время сессии.
MIT ★ 586 обновлён 2026-10-26
/plugin marketplace add karanb192/claude-code-hooks
/plugin install config-watch@claude-code-hooksЧто делает config-watch
Плагин ставит хук на событие ConfigChange. Оно срабатывает, когда посреди сессии меняются настройки (user, project, local, policy) или файлы скиллов. Установщик, npm postinstall или другой процесс правит конфиг за спиной Claude, а вы получаете systemMessage с именем источника и, если payload его содержит, путём к файлу. По умолчанию хук только предупреждает и выходит с кодом 0.
С CONFIG_WATCH_BLOCK=true хук выходит с кодом 2 и пишет причину в stderr, изменение не применяется. Исключение — policy_settings: хуки не могут их блокировать, там всегда предупреждение. ConfigChange срабатывает и на ваши собственные правки через /config или редактор, поэтому блокировку включают на ужесточённой машине, а не по умолчанию.
Схему payload в документации не описали, так что скрипт разбирает его с запасом: принимает source, config_source или matcher и file_path либо path. Каждое событие вместе с сырым payload уходит в ~/.claude/hooks-logs/<date>.jsonl. Сетевых вызовов нет, скрипт использует только fs и path. В паре с config-guard работа делится: тот закрывает записи самого агента, этот — внешний путь.
Какие задачи решает
- заметить, что установщик переписал
.claude/settings.jsonпосреди сессии - остановить npm postinstall, который меняет настройки на ходу
- увидеть, какой источник вызвал изменение конфига
- разобрать сырой payload
ConfigChangeиз лога - прикрыть внешние правки, пока config-guard стережёт записи агента
Примеры запросов агенту
- Включи блокировку изменений конфига: поставь
CONFIG_WATCH_BLOCK=trueи перезапусти сессию. - Покажи, какие события
ConfigChangeзаписались в~/.claude/hooks-logs/<date>.jsonl. - Разберись, кто переписал настройки, и посмотри сырой payload в логе хука.
Как установить config-watch
Через маркетплейс плагинов
/plugin marketplace add karanb192/claude-code-hooks/plugin install config-watch@claude-code-hooksПо шагам, с командами для каждой платформы: Плагины Claude Code: маркетплейсы, установка и как собрать свой
Вопросы о config-watch
Как установить config-watch в Claude Code?
Сначала /plugin marketplace add karanb192/claude-code-hooks, затем /plugin install config-watch@claude-code-hooks. После этого перезапустите Claude.
Что делает config-watch?
Добавляет хук ConfigChange, который сообщает через systemMessage о правках настроек или скиллов во время сессии, а в режиме блокировки не даёт им примениться.
Можно ли заблокировать изменения policy_settings?
Нет. Хуки не могут блокировать policy_settings, поэтому такие изменения в любом режиме приходят как предупреждение.
Исходный текст
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