File Watcher with Header Management

# File Watcher with Header Management

A Python-based file watching system that automatically manages headers in text files and maintains a clean, focused project tree structure. Perfect for maintaining consistent file headers and documentation across your project.

## Quick Start

1. Clone the repository:
   ```bash
   git clone https://github.com/johnbenac/cursor-watchful-headers.git
   ```

2. Run the installation script:
   ```bash
   python cursor-watchful-headers/install.py
   ```
   This will:
   - Copy `watcher.py` and `.watchlist` to your current directory (if they don't already exist)
   - Install the required dependencies

3. Start the watcher:
   ```bash
   python watcher.py
   ```

## Configuration Files

The watcher uses three main configuration files:

1. `.watchlist`: Lists files that should receive headers and be monitored for changes
   ```
   # One file per line
   src/components/header.js
   src/utils/helpers.py
   ```

2. `.donotwatchlist`: Controls tree visualization in `.cursorrules`
   ```
   # Regex patterns to exclude from tree display
   node_modules     # Hide node_modules directory
   build/.*         # Hide build directory and contents
   .*\.pyc$        # Hide Python cache files
   ```
   Note: `.donotwatchlist` only affects what appears in the tree structure. It does not prevent files listed in `.watchlist` from receiving headers.

3. `.cursorrules`: Automatically maintained tree structure
   - Updated whenever watched files change
   - Excludes directories/files matching `.donotwatchlist` patterns
   - Provides clean, focused context for LLM coding agents
   - Labels unwatched files to help identify what should be monitored

## Tree Visualization Features

The tree structure in `.cursorrules` provides two key features:

1. **Directory Exclusion** (via `.donotwatchlist`):
   ```
   foods/
   ├── fruits/
   │   ├── apple.txt
   │   └── banana.txt
   └── vegetables/       # guilty_pleasures/ directory is hidden
       ├── carrot.txt
       └── spinach.txt
   ```

2. **Unwatched File Labeling**:
   ```
   ├── src/
   │   ├── main.py
   │   ├── utils.py  # unwatched
   │   └── config.py  # unwatched
   ```
   Files marked with "# unwatched" are visible in the tree but not receiving headers.

### How This Helps LLMs

The combination of these features helps LLMs maintain better project awareness:

1. **Clean Context**: 
   - `.donotwatchlist` hides irrelevant directories (build outputs, dependencies)
   - Keeps the tree focused on project-specific files
   - LLMs are automatically reminded to suggest excluding directories that don't add value
   - Build outputs, cache directories, and other non-essential paths are kept out of the context

2. **Active Monitoring**:
   - "# unwatched" labels help LLMs identify files that should potentially be monitored
   - When an LLM sees an unwatched file being modified, it can suggest:
     ```
     "I notice utils.py is marked as unwatched. Would you like me to add it to .watchlist
     to ensure it receives proper headers and monitoring?"
     ```

3. **Intelligent Recommendations**:
   - LLMs can analyze patterns of watched vs. unwatched files
   - Suggest consistent monitoring strategies (e.g., "Other Python files in this directory are watched, should we watch this one too?")
   - Help maintain consistent header management across similar file types
   - Proactively suggest adding directories to `.donotwatchlist` when they don't add value to the context

4. **Self-Optimizing Context**:
   - LLMs receive automatic reminders in the `.cursorrules` header to:
     ```
     NOTE TO ASSISTANT: If you notice directories that don't add value to the context
     (like build outputs, cache, etc), suggest adding them to .donotwatchlist
     to keep the tree structure focused and clean.
     ```
   - This creates a feedback loop where LLMs help maintain an increasingly clean and relevant context
   - Common examples of directories to exclude:
     - `node_modules/`, `venv/`, `__pycache__/` (dependencies)
     - `build/`, `dist/`, `out/` (build artifacts)
     - `.git/`, `.svn/` (version control)
     - `tmp/`, `temp/`, `cache/` (temporary files)
     - `logs/`, `coverage/` (operational data)

This labeling system creates a self-documenting workflow where:
- The tree structure shows what exists
- `.donotwatchlist` controls what's visible
- "# unwatched" labels guide what should be monitored
- LLMs proactively suggest improvements to both monitoring and context management
- The context becomes increasingly focused and relevant over time

## Example: Tree Visualization Control

Consider this project structure with some files we want to hide from the tree:

```
foods/
├── fruits/
│   ├── apple.txt
│   └── banana.txt
├── vegetables/
│   ├── carrot.txt
│   └── spinach.txt
└── guilty_pleasures/    # Directory we want to hide
    ├── chocolate.txt
    ├── cake.txt
    └── icecream.txt
```

By adding `guilty_pleasures` to `.donotwatchlist`:
```
guilty_pleasures   

... (truncated)