CwdChanged and FileChanged Hooks / Claude Code v2.1.83

What

Two new hook event types that trigger automation when the working directory changes or when specific files are modified.

Usage in .claude/hooks.json:

{
  "hooks": {
    "CwdChanged": [{
      "command": "my-script.sh",
      "timeout": 10000
    }],
    "FileChanged": [{
      "command": "on-file-change.sh",
      "matcher": "src/**/*.ts",
      "timeout": 10000
    }]
  }
}

Details

CwdChanged: Fires after the working directory changes. Input JSON includes old_cwd and new_cwd. Hook output can include watchPaths to dynamically register additional file watchers via hookSpecificOutput
FileChanged: Fires when a watched file changes, is added, or is removed. Input JSON includes file_path and event (one of change, add, unlink). The matcher field specifies file glob patterns to watch
Both hook types set CLAUDE_ENV_FILE — write bash exports there to inject environment variables into subsequent BashTool commands
File watching uses chokidar under the hood for cross-platform filesystem monitoring

Evidence

New hook types (search for "CwdChanged", "FileChanged", "cwdchanged-hook-", "filechanged-hook-")

Strings lifted out of the shipped bundle, so the claim above can be checked against them.

How sure we are

One source agreesOne thing we can check says the same as this entry.

Anthropic's release notes agreeAdded CwdChanged and FileChanged hook events for reactive environment management (e.g., direnv)

See this entry in the whole of v2.1.83 →

The build it came inv2.1.83

24 Mar 2026 · 25 entries, this one is #3.

Either side of it

v2.1.81Older
v2.1.84Newer

Open the release →

Names in this entry

hookCwdChanged
When the working directory changes, for example when Claude executes a cd command. Useful for reactive environment management with tools like direnv
hookFileChanged
When a watched file changes on disk. The matcher field specifies which filenames to watch
settinghookSpecificOutput
Hooks can now return permissionDisplay in their output, next to additionalContext, to supply details for a permission prompt
envCLAUDE_ENV_FILE
Session environment files can be read and written through a storage layer instead of directly on disk.

Anthropic's note

Upstream's own release notes for v2.1.83 name something this entry names, so the two are probably about the same change. Probably: the pairing is made on a shared name rather than on the words around it.

Added CwdChanged and FileChanged hook events for reactive environment management (e.g., direnv)

Is this right?