file-watcher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

File Watcher

文件监听器

Use Claude Code's

FileChanged

and

CwdChanged

hooks to create reactive workflows that respond to file system changes.

使用 Claude Code 的

FileChanged

和

CwdChanged

Hook，创建可响应文件系统变更的响应式工作流。

Trigger

触发场景

Use when:

Setting up auto-reload for config changes
Watching for dependency updates
Monitoring build output
Creating reactive development workflows

适用于：

为配置变更设置自动重新加载
监听依赖项更新
监控构建输出
创建响应式开发工作流

How File Watching Works

文件监听的工作原理

Claude Code's

SessionStart

and

CwdChanged

hooks support returning

watchPaths

to register file watchers. The current

cwd-changed.js

script focuses on env injection; to add watch registration, your hook script must output this JSON structure:

json

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "watchPaths": [
      "/absolute/path/to/.env",
      "/absolute/path/to/package.json"
    ]
  }
}

When watched files change, the

FileChanged

hook fires with:

json

{
  "hook_event_name": "FileChanged",
  "file_path": "/path/to/changed/file",
  "event": "change"
}

Claude Code 的

SessionStart

和

CwdChanged

Hook 支持返回

watchPaths

以注册文件监听器。当前的

cwd-changed.js

脚本侧重于 env 注入；要添加监听注册，Hook 脚本必须输出以下 JSON 结构：

json

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "watchPaths": [
      "/absolute/path/to/.env",
      "/absolute/path/to/package.json"
    ]
  }
}

被监听的文件发生变更时，

FileChanged

Hook 会触发并携带以下信息：

json

{
  "hook_event_name": "FileChanged",
  "file_path": "/path/to/changed/file",
  "event": "change"
}

Environment Injection

环境变量注入

CwdChanged

and

FileChanged

hooks can write to

CLAUDE_ENV_FILE

to inject environment variables into subsequent Bash commands:

bash

echo "export PROJECT_TYPE=node" >> "$CLAUDE_ENV_FILE"
echo "export TEST_CMD='npm test'" >> "$CLAUDE_ENV_FILE"

CwdChanged

和

FileChanged

Hook 可以写入

CLAUDE_ENV_FILE

，将环境变量注入后续的 Bash 命令：

bash

echo "export PROJECT_TYPE=node" >> "$CLAUDE_ENV_FILE"
echo "export TEST_CMD='npm test'" >> "$CLAUDE_ENV_FILE"

Common Watch Patterns

常见监听模式

Watch .env for Changes

监听 .env 的变更

javascript

const envFile = path.join(projectRoot, '.env');
if (fs.existsSync(envFile)) {
  output.hookSpecificOutput = {
    hookEventName: 'SessionStart',
    watchPaths: [envFile]
  };
}

javascript

const envFile = path.join(projectRoot, '.env');
if (fs.existsSync(envFile)) {
  output.hookSpecificOutput = {
    hookEventName: 'SessionStart',
    watchPaths: [envFile]
  };
}

Watch package.json for Dependency Changes

监听 package.json 中的依赖项变更

Detect when dependencies change and remind to run

npm install

检测依赖项发生变更时，提醒运行

npm install

。

Watch tsconfig.json for Config Changes

监听 tsconfig.json 的配置变更

Remind to restart TypeScript checks when config changes.

配置发生变更时，提醒重新启动 TypeScript 检查。

Setup

设置

Add to hooks.json:

json

{
  "FileChanged": [{
    "matcher": ".env|package.json|tsconfig.json",
    "hooks": [{
      "type": "command",
      "command": "node scripts/file-changed.js"
    }]
  }]
}

在 hooks.json 中添加：

json

{
  "FileChanged": [{
    "matcher": ".env|package.json|tsconfig.json",
    "hooks": [{
      "type": "command",
      "command": "node scripts/file-changed.js"
    }]
  }]
}

Rules

规则

Use absolute paths for watchPaths (required by Claude Code)
Matcher uses pipe-separated filenames
Watcher uses 500ms stability threshold and 200ms poll interval
Keep file-changed handlers fast (<5s) to avoid blocking
Use
```
CLAUDE_ENV_FILE
```
for injecting env vars, not direct export

```
watchPaths
```
必须使用绝对路径（Claude Code 的要求）
Matcher 使用竖线分隔文件名
文件监听器采用 500ms 稳定阈值和 200ms 轮询间隔
文件变更处理程序应保持快速（少于 5 秒），以避免阻塞
使用
```
CLAUDE_ENV_FILE
```
注入环境变量，不要直接 export