winsorllc 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
| Option | Description | Default |
|---|---|---|
--command CMD |
Command to run on change | Required |
--file FILE |
Watch single file | None |
--files "F1,F2,..." |
Watch multiple files | None |
--files-from FILE |
Read file list from file | None |
--pattern GLOB |
File pattern to match | * |
--events TYPES |
Events: create,modify,delete | all |
--recursive |
Watch subdirectories | true |
--no-recursive |
Don't recurse | false |
--debounce SECS |
Debounce time | 0 |
--debounce-file |
Debounce per file | false |
--daemon |
Run in background | false |
--pidfile FILE |
PID file for daemon | None |
--timeout SECS |
Stop after N seconds | None |
--quiet |
Suppress output | false |
--verbose |
Show all events | false |
Events
| Event | Description |
|---|---|
create |
File or directory created |
modify |
File content modified |
delete |
File or directory deleted |
move |
File moved (renamed) |
access |
File accessed (read) |
attrib |
File attributes changed |
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
$FILEand$EVENTenvironment 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