Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
Open on GitHub

What 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-workflow

This installs the whole pro-workflow plugin with all its skills

2Skills CLI (Vercel)

npx skills add rohitg00/pro-workflow --skill file-watcher -a claude-code

3Manually: put the files in place

~/.claude/skills/file-watcher/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/file-watcher/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set83

The whole set →
cost-analyst cost-analyst reviews session token use, spots costly operations, and checks cache hits to suggest concrete ways to lower session costs. CX Codex ★ 2,966repo stars context-engineer context-engineer audits context window usage across project files, tools, and MCP servers. Useful when sessions run slow or hit token compaction too often. CX Codex ★ 2,966repo stars pre-flight-discipline The pre-flight-discipline rule makes Claude Code surface assumptions, limit edits to the request, and verify multi-step work. It fits projects where drive-by changes are a concern. CX Codex +1 ★ 2,966repo stars smart-commit smart-commit runs lint, typecheck and tests before a commit, scans staged code for leftovers, then writes a conventional commit message from the diff. CX Codex +1 ★ 2,966repo stars commit Runs project checks, reviews staged changes, and creates a focused git commit. Use it when a change is ready to be recorded. CX Codex +1 ★ 2,966repo stars mcp-audit mcp-audit analyzes connected MCP servers for token overhead, redundancy, and unused configurations. Run when sessions slow down or before connecting a new server. CX Codex +1 ★ 2,966repo stars tdd tdd guides Claude Code through a strict test-driven development loop: write a failing test, pass it with minimal code, and clean up. CX Codex +1 ★ 2,966repo stars module-shape The module-shape rule keeps public module APIs small while hiding complexity inside. Use it when designing modules or reviewing tests and dependencies. CX Codex +1 ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open