watchdog
Filesystem events monitoring library — watches directories for file creation, modification, deletion, and movement. watchdog features: Observer thread for non-blocking monitoring, FileSystemEventHandler base class, on_created/on_modified/on_deleted/on_moved event handlers, PatternMatchingEventHandler for glob-based filtering, LoggingEventHandler for debug output, recursive= flag for deep directory watching, platform-native backends (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows), and fallback polling backend. Used for hot-reload, live compilation, and file synchronization.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Filesystem monitoring — operates with process permissions. Watching directories containing secrets: event handlers receive file paths (not contents); reading file content in handler uses normal file I/O permissions. Symlink traversal: recursive=True follows symlinks — could escape intended directory; validate event.src_path is within watched root before processing.
⚡ Reliability
Best When
Local filesystem monitoring for hot-reload, live compilation, and file sync — watchdog provides cross-platform native filesystem events with clean Python API.
Avoid When
Network filesystems (use polling with explicit scheduling), extremely high-frequency events (use OS APIs), or when event ordering guarantees are required.
Use Cases
- • Agent filesystem watch — from watchdog.observers import Observer; from watchdog.events import FileSystemEventHandler; class Handler(FileSystemEventHandler): def on_modified(self, event): if not event.is_directory: process_file(event.src_path); observer = Observer(); observer.schedule(Handler(), path='/watch/dir', recursive=True); observer.start() — non-blocking watch; agent monitors directory for changes in background thread
- • Agent pattern filtering — from watchdog.events import PatternMatchingEventHandler; handler = PatternMatchingEventHandler(patterns=['*.py', '*.json'], ignore_patterns=['*.pyc'], ignore_directories=True, case_sensitive=False); observer.schedule(handler, '/src', recursive=True) — filtered watch; agent responds only to specific file types; patterns use fnmatch glob syntax
- • Agent hot reload — handler = MyHandler(); observer = Observer(); observer.schedule(handler, '.', recursive=True); observer.start(); try: while True: time.sleep(1) except KeyboardInterrupt: observer.stop(); observer.join() — hot reload loop; agent watches for changes and reloads configuration or reprocesses files; main thread sleeps while observer thread fires events
- • Agent event details — def on_created(self, event): path = event.src_path; is_dir = event.is_directory; print(f'Created: {path}'); def on_moved(self, event): print(f'Moved: {event.src_path} -> {event.dest_path') — event attributes; agent accesses event.src_path for all events; on_moved provides both src_path and dest_path
- • Agent file stabilization — class StableHandler(FileSystemEventHandler): def on_modified(self, event): time.sleep(0.1); size1 = os.path.getsize(event.src_path); time.sleep(0.1); size2 = os.path.getsize(event.src_path); if size1 == size2: process(event.src_path) — stability check; agent waits for file to stop changing before processing; prevents partial file reads during large file writes
Not For
- • High-frequency event processing — watchdog may miss events during heavy IO; for reliable event processing use OS-native APIs directly
- • Network filesystem watching — NFS/CIFS don't support inotify; watchdog falls back to polling with high latency
- • Windows service file watching — watchdog observer is a thread not service; for Windows service use win32file directly
Interface
Authentication
No auth — filesystem monitoring library. Filesystem permissions control what can be watched.
Pricing
watchdog is Apache 2.0 licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Event handler runs in observer thread — FileSystemEventHandler.on_modified() runs in watchdog's observer thread not main thread; agent code: event handlers must be thread-safe; avoid shared mutable state without locks; for long processing: put event in queue.Queue() and process in main thread; blocking handler blocks all subsequent events
- ⚠ Duplicate events are common — a single file save generates multiple events (modified, modified again for metadata); editor atomic saves: delete + create; agent code: debounce events with a timer: use threading.Timer or track last-processed timestamp; for editors: on_created may be more reliable than on_modified for 'file saved' semantics
- ⚠ observer.stop() must be followed by observer.join() — observer.stop() signals the thread to stop; observer.join() waits for thread to actually exit; agent code without join() may have the observer thread still running after script exit; always: observer.stop(); observer.join() — typically in finally block or signal handler
- ⚠ recursive=True watches ALL subdirectories — observer.schedule(handler, '/', recursive=True) watches entire filesystem; on Linux with inotify: inotify watch limit may be hit (sysctl fs.inotify.max_user_watches); agent code on large directories: increase limit or use non-recursive with specific subdirs; event.is_directory to filter directory events
- ⚠ File deletion events may have stale paths — on_deleted event.src_path refers to deleted file; os.path.exists(event.src_path) is False; agent code processing deletions: use path string directly for logging or cleanup; do not attempt to read file content on deletion event
- ⚠ macOS FSEvents may batch events — macOS can batch multiple events and deliver at once; on_modified may fire after multiple changes; agent code expecting real-time single-event delivery: add small sleep in event handler before processing to let file settle; or use kqueue-based observer for lower latency
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for watchdog.
Scores are editorial opinions as of 2026-03-06.