file-watcher（文件观察者）

File Watcher Skill

Monitor files and directories for changes and trigger actions when changes occur.

When to Use

✅ USE this skill when:

• "Watch for file changes"
• "Run command when file changes"
• "Monitor directory for new files"
• "Execute script on file create"
• "Watch multiple files for changes"

When NOT to Use

❌ DON'T use this skill when:

• One-time file check → use test/read commands
• Scheduled monitoring → use cron
• Need persistent logging → use dedicated monitoring

Commands

Watch Directory

{baseDir}/watch.sh <directory> --command "echo 'Changed'"
{baseDir}/watch.sh ./src --command "npm run build"
{baseDir}/watch.sh ./logs --command "./process.sh" --pattern "*.log"

Watch Single File

{baseDir}/watch.sh --file config.json --command "echo 'Config changed'"
{baseDir}/watch.sh --file /var/log/app.log --command "tail -5 /var/log/app.log"

Watch Multiple Files

{baseDir}/watch.sh --files "file1.txt,file2.txt,file3.txt" --command "echo 'Changed'"
{baseDir}/watch.sh --files-from list.txt --command "echo 'Changed'"

Event Types

{baseDir}/watch.sh ./src --command "make" --events create,modify,delete
{baseDir}/watch.sh ./src --command "make" --events create
{baseDir}/watch.sh ./src --command "make" --events modify

Background Mode

{baseDir}/watch.sh ./src --command "make" --daemon
{baseDir}/watch.sh ./src --command "make" --pidfile /tmp/watcher.pid

Debounce

{baseDir}/watch.sh ./src --command "npm run build" --debounce 2
{baseDir}/watch.sh ./src --command "npm run build" --debounce-file

Options

Events

Output Format

[2026-02-25 20:41:00] MODIFY /path/to/file.txt
Running: echo 'Changed'
...
[2026-02-25 20:41:01] CREATE /path/to/newfile.txt
Running: echo 'Changed'
...

With --json:

{"event": "MODIFY", "file": "/path/to/file.txt", "timestamp": "2026-02-25T20:41:00Z", "command_output": "..."}

Examples

Watch and rebuild:

{baseDir}/watch.sh ./src --command "npm run build" --debounce 1

Watch for new log files:

{baseDir}/watch.sh ./logs --command "./new-log.sh" --events create

Watch config and restart:

{baseDir}/watch.sh --file config.json --command "pm2 restart app"

Watch multiple files:

{baseDir}/watch.sh --files "config.json,.env,package.json" --command "npm run build"

Watch in background:

{baseDir}/watch.sh ./src --command "make" --daemon --pidfile /tmp/watcher.pid

Watch for deleted files:

{baseDir}/watch.sh ./uploads --command "echo 'File deleted'" --events delete

Debouncing

The --debounce option prevents rapid-fire commands:

• --debounce N: Wait N seconds after the last event before running the command
• --debounce-file: Track debounce per file independently

# Wait 2 seconds after last change
{baseDir}/watch.sh ./src --command "build.sh" --debounce 2

# Debounce per file (each file gets its own timer)
{baseDir}/watch.sh ./src --command "process.sh" --debounce-file --debounce 1

Notes

• Uses inotifywait (Linux) or fswatch (macOS) when available
• Falls back to polling on systems without native support
• Command receives $FILE and $EVENT environment variables
• Recursive by default for directories
• Can watch thousands of files efficiently
• Clean shutdown with SIGTERM or SIGINT

Dependencies

• Linux: inotifywait (inotify-tools package)
• macOS: fswatch (brew install fswatch)
• Both: Polling fallback with 1-second interval