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 $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