file-watcher — Claude Code skill: what it does, how to install
file-watcher configures Claude Code hooks to react to changes in configuration files, dependencies, and environment files.
MIT ★ 2,966 updated 2026-09-29
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflowWhat file-watcher does
This skill sets up reactive workflows using Claude Code's SessionStart, CwdChanged, and FileChanged hooks. When monitored files like .env or package.json change, the corresponding hook fires with the changed file path.
Hook scripts can inject environment variables into subsequent session commands by appending them to CLAUDE_ENV_FILE. Claude Code requires absolute paths in watchPaths, and handler scripts must finish in under 5 seconds to prevent blocking the environment.
What it helps with
- track .env updates and inject new variables into the session
- detect package.json modifications to trigger dependency installs
- monitor tsconfig.json edits to rerun TypeScript checks
- configure reactive file-watching hooks in hooks.json
Example prompts for the agent
- Set up file watching for package.json to notify when dependencies change
- Configure a FileChanged hook to reload .env variables into CLAUDE_ENV_FILE
- Generate a hooks.json snippet to watch tsconfig.json for modifications
How to install file-watcher
1Plugin marketplace
/plugin marketplace add rohitg00/pro-workflow/plugin install pro-workflow@pro-workflowThis installs the whole pro-workflow plugin with all its skills
2Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill file-watcher -a claude-code3Manually: put the files in place
~/.claude/skills/file-watcher/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/file-watcher/
1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill file-watcher -a codex2Manually: put the files in place
.agents/skills/file-watcher/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill file-watcher -a cursor2Manually: put the files in place
.cursor/skills/file-watcher/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install rohitg00/pro-workflow skills/file-watcher2Manually: put the files in place
.github/skills/file-watcher/SKILL.md1Skills CLI (Vercel)
npx skills add rohitg00/pro-workflow --skill file-watcher -a gemini-cli2Platform CLI
gemini skills install https://github.com/rohitg00/pro-workflow --path skills/file-watcherManually: put the files in place
.devin/skills/file-watcher/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about file-watcher
How to install file-watcher in Claude Code?
Run /plugin marketplace add rohitg00/pro-workflow in Claude Code, then execute /plugin install pro-workflow@pro-workflow.
What does file-watcher do?
It provides patterns to monitor specific files with Claude Code hooks and trigger actions when those files update.
What constraints apply to file-watcher hooks?
The watchPaths parameter strictly requires absolute paths, and handler scripts must complete within 5 seconds to avoid blocking.
Source text
SKILL.md · MIT
---
name: file-watcher
description: Configure file watching hooks to auto-react to config changes, env file updates, and dependency modifications. Use to set up reactive workflows.
user-invocable: true
---
# File Watcher
Use Claude Code's `FileChanged` and `CwdChanged` hooks to create reactive workflows that respond to file system changes.
## 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"
}
```
## 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"
```
## Common Watch Patterns
### Watch .env for Changes
```javascript
const envFile = path.join(projectRoot, '.env');
if (fs.existsSync(envFile)) {
output.hookSpecificOutput = {
hookEventName: 'SessionStart',
watchPaths: [envFile]
};
}
```
### Watch package.json for Dependency Changes
Detect when dependencies change and remind to run `npm install`.
### Watch tsconfig.json for Config Changes
Remind to restart TypeScript checks when config changes.
## Setup
Add to 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
© Rohit Ghumare · MIT · rohitg00/pro-workflow