# ADN Note: Watchfiles - High-Performance File Watching Library
## Metadata
**Title**: Watchfiles - High-Performance File Watching for Robotics MCP
**Folder**: infrastructure/tools
**Tags**: infrastructure, development-tools, file-watching, fastapi, uvicorn, cross-platform, performance, robotics-development
**Entity Type**: note
**Created**: 2025-12-17
## Content
# Watchfiles: High-Performance File Watching for Robotics MCP
## Overview
Watchfiles is a cross-platform Python library that provides real-time file system monitoring with native OS API integration. In our Robotics MCP WebApp, it's used by Uvicorn for automatic server reloading during development.
## Technical Specifications
### Version & Integration
- **Version**: 1.1.0
- **Bundled with**: `uvicorn[standard]==0.38.0`
- **Integration**: Automatic FastAPI development reloading
### Core Architecture
```python
# Dual-process system:
# 1. Main server process (FastAPI/WebSockets)
# 2. Reloader process (watchfiles monitoring)
INFO: Started reloader process [485560] using WatchFiles
INFO: Started server process [502800]
```
## Performance Characteristics
### OS-Specific Implementations
- **Windows**: ReadDirectoryChangesW API
- **macOS**: kqueue API
- **Linux**: inotify API
### Benchmarks
- **Memory Usage**: < 10MB for typical projects
- **CPU Usage**: < 1% when idle
- **Response Time**: < 100ms for file changes
- **Debouncing**: Prevents excessive reloads from rapid changes
## Robotics MCP Integration
### Development Workflow
```bash
# Start development server
cd backend && python main.py
# Automatic monitoring begins:
# - Python files (*.py)
# - Config files (*.yaml, *.json)
# - Documentation (*.md)
# Ignores: __pycache__, *.pyc, .git/, etc.
```
### Benefits for Robotics Development
1. **Camera Integration Testing**: Instant reloads when modifying `camera_integration.py`
2. **WebSocket Persistence**: Real-time connections maintained during reloads
3. **LLM Command Testing**: Immediate feedback on AI integration changes
4. **Hardware Interface Updates**: Quick iteration on USB camera controls
## API Reference
### Core Functions
```python
from watchfiles import awatch, Change, DefaultFilter
# Async file watching
async for changes in awatch('./backend'):
for change, path in changes:
if change == Change.modified:
print(f"File changed: {path}")
# Change types
Change.added # File created
Change.modified # File content changed
Change.deleted # File removed
# Smart filtering
filter = DefaultFilter() # Ignores common patterns
```
## Production Considerations
### Development vs Production
```python
# Development (with watchfiles)
uvicorn main:app --reload --host 0.0.0.0 --port 8354
# Production (without watchfiles)
uvicorn main:app --host 0.0.0.0 --port 8354 --workers 4
```
### Security & Performance
- **Disabled in production**: No file system monitoring overhead
- **Memory efficient**: Minimal resource usage
- **Secure**: Prevents potential file system enumeration attacks
## Comparison with Alternatives
| Feature | Watchfiles | Watchdog | Inotify Direct |
|---------|------------|----------|----------------|
| Async Support | ✅ Native asyncio | ❌ Limited | ❌ None |
| Cross-platform | ✅ Windows/macOS/Linux | ✅ All platforms | ❌ Linux-only |
| Performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Memory Usage | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Robotics MCP Fit | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
## Troubleshooting Common Issues
### High CPU Usage
```python
# Use filters to limit watched files
from watchfiles import awatch, DefaultFilter
async for changes in awatch('./', filter=DefaultFilter()):
# Only watches relevant files, ignores cache/git
pass
```
### Windows Camera Issues
```python
# Use DirectShow backend for USB cameras
import cv2
cap = cv2.VideoCapture(0, cv2.CAP_DSHOW)
```
## Future Integration Plans
### Robotics-Specific Enhancements
- **Camera Auto-reconnection**: Automatically reconnect USB cameras after reload
- **State Preservation**: Maintain robot control state across reloads
- **Hardware Monitoring**: Watch for hardware configuration changes
- **Selective Reloading**: Only reload changed modules, not entire server
### Advanced Features
- **Hot Module Replacement**: Update individual modules without full restart
- **Integration Hooks**: Pre/post reload callbacks for hardware cleanup
- **Custom Filters**: Robotics-specific ignore patterns
## Conclusion
Watchfiles is essential infrastructure for the Robotics MCP WebApp development workflow, enabling:
- **Rapid iteration** on camera integration and AI features
- **Seamless development** without manual server restarts
- **Production safety** with automatic disable in deployment
- **Cross-platform consistency** across development environments
It's a perfect example of "boring technology" that enables exciting robotics development.
---
**Related Notes**:
- Robotics MCP Technical Architecture 2025
- Development Workflow 2025 Standards
- FastAPI Backend Implementation
- USB Camera Integration
## Import Instructions
To import this note into Advanced Memory:
1. Copy the content above
2. Use `adn_content` tool with operation="write"
3. Set identifier to "Watchfiles - High-Performance File Watching Library"
4. Set folder to "infrastructure/tools"
5. Set tags to ["infrastructure", "development-tools", "file-watching", "fastapi", "uvicorn", "cross-platform", "performance", "robotics-development"]
