File watcher setup guide

Auto-sync your rules when you save changes to agent files. This guide provides the fastest and most reliable options for each platform.

Quick start

For each platform, we provide two options:

Fastest: Quickest to set up (1-2 minutes)
Most Reliable: Production-ready, handles edge cases

Choose your platform below:

VS Code

VS Code (Fastest: ~2 minutes)

Option 1: VS Code task (fastest)

Create .vscode/tasks.json:


{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "AlignTrue Auto-Sync",
      "type": "shell",
      "command": "aligntrue sync",
      "presentation": {
        "reveal": "silent",
        "panel": "dedicated",
        "showReuseMessage": false
      },
      "runOptions": {
        "runOn": "folderOpen"
      }
    }
  ]
}

Create .vscode/settings.json:


{
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,
  "task.autoDetect": "on"
}

Usage:

Files auto-save after 1 second of inactivity
Task runs aligntrue sync automatically
Silent output (check Terminal if needed)

Option 2: VS Code extension (most reliable)

Install Run on Save extension:

Open Extensions (Cmd/Ctrl+Shift+X)
Search “Run on Save”
Install by emeraldwalk

Create .vscode/settings.json:


{
  "emeraldwalk.runonsave": {
    "commands": [
      {
        "match": "\\.cursor/rules/.*\\.mdc$",
        "cmd": "aligntrue sync"
      },
      {
        "match": "AGENTS\\.md$",
        "cmd": "aligntrue sync"
      }
    ]
  }
}

Advantages:

Only runs on specific file changes
Handles rapid edits gracefully
Shows sync status in output panel

macOS

macOS Terminal

Option 1: fswatch (fastest)

Install:


brew install fswatch

Create watch-sync.sh:


#!/bin/bash
fswatch -o .cursor/rules AGENTS.md | while read; do
  echo "$(date): Files changed, syncing..."
  aligntrue sync
done

Run:


chmod +x watch-sync.sh
./watch-sync.sh

Stop: Ctrl+C

Option 2: nodemon (most reliable)

Install nodemon:

npm

bash npm install -g nodemon

yarn

bash yarn global add nodemon

pnpm

bash pnpm add -g nodemon

bun

bash bun install -g nodemon

Create nodemon.json:


{
  "watch": [".cursor/rules/**/*.mdc", "AGENTS.md"],
  "ext": "mdc,md",
  "exec": "aligntrue sync",
  "delay": 1000
}

Run:


nodemon

Advantages:

Debounces rapid changes (1 second delay)
Handles renames and deletes
Restarts on crash
Production-ready

Linux

Option 1: inotifywait (fastest)

Install (Ubuntu/Debian):


sudo apt-get install inotify-tools

Install (Fedora/RHEL):


sudo dnf install inotify-tools

Create watch-sync.sh:


#!/bin/bash
while inotifywait -r -e modify,create,delete .cursor/rules AGENTS.md; do
  sleep 1  # Debounce
  echo "$(date): Syncing..."
  aligntrue sync
done

Run:


chmod +x watch-sync.sh
./watch-sync.sh

Option 2: nodemon (most reliable)

Same as macOS Option 2 above.

Install nodemon:

npm

bash npm install -g nodemon

yarn

bash yarn global add nodemon

pnpm

bash pnpm add -g nodemon

bun

bash bun install -g nodemon

Create nodemon.json: (same as macOS)

Run:


nodemon

Windows

Option 1: PowerShell FileSystemWatcher (fastest)

Create watch-sync.ps1:


$watcher = New-Object System.IO.FileSystemWatcher
$watcher.Path = ".cursor\rules"
$watcher.Filter = "*.mdc"
$watcher.IncludeSubdirectories = $true
$watcher.EnableRaisingEvents = $true
 
$action = {
    Start-Sleep -Seconds 1  # Debounce
    Write-Host "$(Get-Date): Syncing..."
    aligntrue sync
}
 
Register-ObjectEvent $watcher "Changed" -Action $action
Register-ObjectEvent $watcher "Created" -Action $action
Register-ObjectEvent $watcher "Deleted" -Action $action
 
Write-Host "Watching .cursor\rules for changes..."
while ($true) { Start-Sleep -Seconds 1 }

Run:


.\watch-sync.ps1

Stop: Ctrl+C

Option 2: nodemon (most reliable)

Same as macOS/Linux Option 2 above.

Install nodemon:

npm

powershell npm install -g nodemon

yarn

powershell yarn global add nodemon

pnpm

powershell pnpm add -g nodemon

bun

powershell bun install -g nodemon

Create nodemon.json: (same format, use forward slashes)

Run:


nodemon

Background service (production)

For always-on file watching, run as a background service.

macOS: launchd

Create ~/Library/LaunchAgents/com.aligntrue.watch.plist:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.aligntrue.watch</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/nodemon</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/path/to/your/project</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

Load service:


launchctl load ~/Library/LaunchAgents/com.aligntrue.watch.plist

Unload service:


launchctl unload ~/Library/LaunchAgents/com.aligntrue.watch.plist

Linux: systemd

Create ~/.config/systemd/user/aligntrue-watch.service:


[Unit]
Description=AlignTrue Auto Sync
After=default.target
 
[Service]
Type=simple
WorkingDirectory=/path/to/your/project
ExecStart=/usr/bin/nodemon
Restart=always
 
[Install]
WantedBy=default.target

Enable and start:


systemctl --user enable aligntrue-watch.service
systemctl --user start aligntrue-watch.service

Check status:


systemctl --user status aligntrue-watch.service

Windows: Task Scheduler

Open Task Scheduler
Create Basic Task
Name: “AlignTrue Auto Sync”
Trigger: “When I log on”
Action: “Start a program”
Program: nodemon
Start in: C:\path\to\your\project
Finish

Troubleshooting

Sync runs too often

Problem: File saves trigger multiple syncs

Solution: Add debounce delay


{
  "delay": 2000 // Wait 2 seconds before syncing
}

Sync doesn’t trigger

Problem: File watcher not detecting changes

Solutions:

Check file paths are correct
Verify aligntrue sync works manually
Check watcher is running (ps aux | grep nodemon)
Restart watcher service

VS Code task won’t run

Problem: Task not executing on file save

Solutions:

Open Command Palette (Cmd/Ctrl+Shift+P)
Search “Tasks: Run Task”
Select “AlignTrue Auto-Sync”
Check Terminal output for errors

High CPU usage

Problem: File watcher using too much CPU

Solutions:

Exclude unnecessary directories:


{
  "ignore": ["node_modules", ".git", "dist"]
}

Increase delay between checks
Use more targeted watch patterns

Permission errors

Problem: “EACCES” or “permission denied”

Solutions (macOS/Linux):


chmod +x watch-sync.sh
chmod 755 .cursor/rules

Solutions (Windows):

Run PowerShell as Administrator
Check file permissions in folder properties

Performance tips

Watch specific directories only (not entire project)
Add debounce delay (1-2 seconds)
Exclude large directories (node_modules, .git)
Use nodemon for production (most optimized)
Limit concurrent syncs (nodemon handles this)

Recommendation by use case

Use Case	Recommendation	Why
Solo dev, VS Code	VS Code Task	Built-in, no install
Solo dev, any editor	nodemon	Universal, reliable
Team, CI/CD	systemd/launchd	Always on, restarts
Windows power user	PowerShell	Native, no dependencies
Quick experiment	fswatch/inotifywait	Minimal setup

Next steps

Choose option for your platform
Set up file watcher (fastest option first)
Edit .cursor/rules/*.mdc or AGENTS.md
Save and verify sync runs automatically
If issues, try “most reliable” option

Questions? Check docs/troubleshooting.md or open an issue.

Last Updated: 2025-10-28