# ConfigChange Hook

> The event when a settings or skill file changes.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** ConfigChange

## Think of it like

It is like an alarm on a cupboard. It tells you when someone opens it.

## Definition

ConfigChange is the hook event that fires when a settings file or a skill file changes in a session. The matcher names where the change came from, such as user_settings, project_settings or skills. A hook can block the change with exit code 2, but not a change to policy settings. It is used to log changes or stop risky ones.

## Example

Jack's team wants a log of every settings change. Their ConfigChange hook writes what changed to an audit file.

## Example code

```json
{
  "hooks": {
    "ConfigChange": [
      { "matcher": "project_settings|local_settings", "hooks": [{ "type": "command", "command": "./audit-config.sh" }] }
    ]
  }
}
```

Audit changes to the project's settings.

## Why it matters

Settings decide what Claude may do. A quiet change there is worth knowing about.

## Common mistake

Expecting it to catch a rule you saved from a prompt in this session. That change skips the hook here.

## Three principles

- **When settings change.** Or skills.
- **Can block.** Not policy.
- **Some changes skip it.** Saved answers.

## Related terms

- [Claude Code Hook](https://learn.benibix.com/term/ai/claude-code-hook)
- [Permission Rule](https://learn.benibix.com/term/ai/permission-rule)
- [Claude Code Skill](https://learn.benibix.com/term/ai/claude-code-skill)

---

Source: https://learn.benibix.com/term/ai/configchange-hook
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
