# FileChanged Hook

> The event when a watched file changes, no matter what changed it.

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

## Think of it like

It is like a dog that barks when a door opens. It does not care who opened it.

## Definition

FileChanged is the hook event that fires when a watched file changes on disk. It does not care what changed it: an edit by Claude, a script, or another program. The matcher lists the file names to watch, split by |, such as .envrc|.env. These are plain names in the working folder, not patterns. It runs after the change and cannot block it.

## Example

Jack edits .env in his own editor while Claude works. His FileChanged hook reloads it, so Claude's next command sees the new value.

## Example code

```json
{
  "hooks": {
    "FileChanged": [
      { "matcher": ".envrc|.env", "hooks": [{ "type": "command", "command": "direnv export bash >> \"$CLAUDE_ENV_FILE\"" }] }
    ]
  }
}
```

Reload variables when either file changes.

## Why it matters

A hook that matches Edit or Write misses changes made by a script. This one sees them all.

## Common mistake

Writing a pattern like ^\.env as the matcher. It watches a file with that exact odd name.

## Three principles

- **Watched files.** Any writer.
- **Plain names.** Not patterns.
- **After the change.** Cannot block.

## Related terms

- [CwdChanged Hook](https://learn.benibix.com/term/ai/cwdchanged-hook)
- [PostToolUse Hook](https://learn.benibix.com/term/ai/posttooluse-hook)
- [CLAUDE_ENV_FILE](https://learn.benibix.com/term/ai/claude-env-file-variable)

## Told apart from

- [FileChanged vs PostToolUse](https://learn.benibix.com/compare/filechanged-hook-vs-posttooluse-hook): People think a PostToolUse hook on Edit sees every change made to a file in the project. It sees only Claude's own tool calls. A script Claude runs, or your own editor, can change the file and it never fires. FileChanged watches the file itself, so it fires whatever wrote it. But only PostToolUse knows which tool call did it.

![A FileChanged matcher becomes a list of watched files, and a change by any program sets off the hook.](https://learn.benibix.com/diagrams/filechanged-watch-list.svg)

---

Source: https://learn.benibix.com/term/ai/filechanged-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.
