File changer never ran - changed.

CLAUDE.md

@@ -28,6 +28,7 @@ The ESPHome container remains immutable and handles all compilation/deployment o
    - Tracks last modification time per file in `ESPHomeFileHandler.last_modified`
    - Monitors all `.yaml`/`.yml` files directly in the config directory
    - Optionally triggers `git push` when `AUTO_PUSH=true`
+   - In production (Gunicorn), started via `post_fork` hook in first worker only
 
 3. **Git Operations** (app.py)
    - `git_clone()` - Initial clone of Gitea repository on startup
@@ -59,6 +60,15 @@ The service expects a flat structure with each device having its own `.yaml` fil
 - Prevents concurrent operations on the same device
 - Operations run in separate threads spawned from file watcher or webhook handlers
 
+## Project Files
+
+- `app.py` - Main Flask application with file watcher, git operations, and API endpoints
+- `gunicorn_config.py` - Gunicorn configuration with hooks for file watcher initialization
+- `requirements.txt` - Python dependencies
+- `Dockerfile` - Container image definition
+- `docker-compose.yml` - Multi-container orchestration (webhook + esphome services)
+- `CLAUDE.md` - This documentation file
+
 ## Development Commands
 
 ### Local Development (Without Docker)
@@ -259,12 +269,25 @@ On startup, the service:
 3. If yes, configures git user and pulls latest changes
 4. All git operations have 60-second timeout
 
-### Gunicorn Configuration (Dockerfile)
+### Gunicorn Configuration
+
+**Configuration File:** `gunicorn_config.py`
 
 - 2 workers
 - 600 second timeout
 - Binds to 0.0.0.0:5000
 
+**Hooks for File Watcher:**
+- `on_starting` hook: Initializes git repository once before workers are forked
+- `post_fork` hook: Starts file watcher thread in the first worker only (worker.age == 0)
+- This ensures the file watcher runs correctly under Gunicorn without duplicates
+
+**Why hooks are needed:**
+When running under Gunicorn, the `if __name__ == '__main__':` block in app.py is never executed. The hooks ensure that:
+1. Git initialization happens once at startup
+2. File watcher starts in exactly one worker process
+3. Multiple workers don't create duplicate file watchers
+
 ## Docker Compose Architecture
 
 Two services work together: