ConfigChange and InstructionsLoaded Hooks - Claude Code
Fire when settings or CLAUDE.md files change during a session.
ConfigChange and InstructionsLoaded hooks react to updates in settings or memory files during an active session.
What it does
ConfigChange fires when settings.json or related files change. InstructionsLoaded fires when CLAUDE.md, rules, or agents definitions are (re)loaded. The hooks receive what changed and can respond - log the diff, notify the user, invalidate internal state, or reject the change for the current session.
When to use it
- Auditing config drift during long sessions.
- Warning users that their rules changed mid-run.
- Refreshing tool allowlists when MCP config is reloaded.
- Syncing effective config to an external monitoring system.
Gotchas
- These hooks can fire during Claude's own edits to config files. Expect recursion.
- Changes that invalidate the session (new CLAUDE.md rule conflicting with in-flight work) need explicit handling.
- Heavy reload logic slows startup and reloads. Keep it minimal.
Official docs: https://code.claude.com/docs/en/hooks.md#configchange
Technical content at the intersection of AI and development. Building with AI agents, Claude Code, and modern dev tools - then showing you exactly how it works.
Get the weekly deep dive
Tutorials on Claude Code, AI agents, and dev tools - delivered free every week.
Was this helpful?
