Watchers Agent - Run Skill Skill

Watchers Agent - Run Skill

Manual run of the website change monitoring agent

When to use

"run watchers"
"check website changes"
"run website monitoring"
Testing after configuration change

What it does

Watchers Agent monitors target websites (competitors, clients, partners) for changes and sends Telegram notifications when important updates are detected.

How to execute

1. Full run (production)

cd $AGENTS_PATH/watchers
python3 watchers_agent.py

What happens:

Loads configuration
Checks targets that are due for checking (by last_checked)
Downloads content and compares with saved snapshots
Uses Claude Haiku to filter noise
Sends Telegram notifications about important changes
Updates state files

2. Dry-run (testing)

cd $AGENTS_PATH/watchers
python3 watchers_agent.py --dry-run

Use for:

Testing after configuration change
Checking new targets
Debugging without sending notifications
Previewing what would be detected

What does NOT happen:

Does not update state files
Does not send Telegram notifications
Only shows what would have been done

3. Configuration check

cd $AGENTS_PATH/watchers
python3 watchers_agent.py --validate-config

Checks YAML syntax and outputs a list of enabled/disabled targets.

Use before:

Adding new targets
Changing selectors or thresholds
First agent run

4. Telegram test

cd $AGENTS_PATH/watchers
python3 watchers_agent.py --notify-test

Sends a test notification to verify Telegram integration.

5. State reset

# Preview
python3 watchers_agent.py --reset-state --dry-run

# Actual reset (confirmation required)
python3 watchers_agent.py --reset-state

When to use:

After major configuration changes (new selectors)
If state files are corrupted
To re-baseline all targets

WARNING: The next run after reset will treat all targets as new and may send many alerts.

Configuration

Configuration file

$PROJECT_ROOT/monitoring/watchers/watcher_config.yaml

Target example

watchers:
  - name: "Competitor Careers Page"
    url: "https://competitor.com/careers"
    type: webpage
    selector: "div.job-listings"  # CSS selector
    priority: high                 # low|medium|high
    check_interval: "1h"           # "1h", "4h", "24h"
    change_threshold: 5            # % change for alert
    tags: ["competitor", "hiring"]
    related_crm_id: "comp-competitor-001"
    enabled: true

Adding a new target

Open watcher_config.yaml
Add a new element to the watchers list
Find the correct CSS selector (DevTools -> Inspect)
Set enabled: true
Run --validate-config to check
Run --dry-run for testing
Run without flags for production

Output

Console

[2026-02-12 10:00:00] Loading configuration...
[2026-02-12 10:00:00] Found 5 target(s) due for checking
[2026-02-12 10:00:01] Processing [1/5]: Competitor Careers Page
[2026-02-12 10:00:03]   CHANGE DETECTED: 12.3% (modified_content)
[2026-02-12 10:00:05]   MEANINGFUL: job_posting - New position posted
[2026-02-12 10:00:10] Done: 5 checked, 2 changed, 1 alerts, 0 errors

Telegram Alert

🔥 URGENT - Website Change Alert

**Competitor Careers Page**
https://competitor.com/careers

Category: Job Posting
Tags: competitor, hiring
Change: 12.3%

New senior engineer position posted for ML team

Diff preview:

Senior ML Engineer - Remote
We are hiring a senior engineer to join our ML team...


💡 Outreach Trigger Detected
Suggested action: Review competitor hiring activity
Related CRM: comp-competitor-001

State Files

$PROJECT_ROOT/monitoring/watchers/state/competitor_com_careers.json

{
  "last_checked": "2026-02-12T10:00:00",
  "content_hash": "abc123...",
  "content_text": "Full page content...",
  "metadata": {
    "word_count": 1523,
    "fetch_timestamp": "2026-02-12T10:00:00",
    "http_status": 200
  },
  "failure_count": 0,
  "last_alert_sent": "2026-02-12T10:00:00"
}

Troubleshooting

"Selector not found"

CSS selector was not found on the page.

Fix:

Open URL in browser
Right-click -> Inspect -> find the correct element
Update selector in config

Too many false positives

Changes detected but not meaningful (timestamps, view counts).

Fix:

Use a more specific selector (exclude dynamic content)
Increase change_threshold for noisy targets
AI filtering should filter these automatically

Telegram not working

Check:

Run --notify-test
Check tg-tools session files
Look at stderr logs
Check pending_alerts.txt for failed alerts

Missed changes

Changes occurred but no alert was sent.

Check:

enabled: true in config?
Change >= change_threshold? Decrease threshold
AI filter rejected as noise? Check state file diff
Check watcher_log.json for errors

Emergency Stop

If the agent is flooding Telegram:

# Create PAUSE file
touch $PROJECT_ROOT/monitoring/watchers/PAUSE

# Agent will skip the next run

# Remove PAUSE to resume
rm $PROJECT_ROOT/monitoring/watchers/PAUSE

Scheduling (launchd)

Install

cp $AGENTS_PATH/watchers/com.yourcompany.watchers-agent.plist \
   ~/Library/LaunchAgents/

launchctl load ~/Library/LaunchAgents/com.yourcompany.watchers-agent.plist

Check Status

launchctl list | grep watchers

View Logs

# stdout
tail -f /tmp/watchers-agent.log

# stderr (main logs here)
tail -f /tmp/watchers-agent-error.log

Uninstall

launchctl unload ~/Library/LaunchAgents/com.yourcompany.watchers-agent.plist
rm ~/Library/LaunchAgents/com.yourcompany.watchers-agent.plist

Files

| File | Purpose | |------|---------| | watchers_agent.py | Main script | | watcher_config.yaml | Configuration | | watcher_log.json | Run history (last 100) | | pending_alerts.txt | Failed alerts fallback | | state/*.json | State files per target | | PAUSE | Emergency stop (create to pause) |

Email Agent ($GOOGLE_TOOLS_PATH/email_agent.py) - similar pattern
Daily Briefing (future) - will include watcher alerts
CRM Add/Update (future) - auto-create tasks on triggers
Touch Scheduler (future) - schedule follow-ups

Owner

Your Name (your@email.com)

Agent Skills: Watchers Agent - Run Skill

Install this agent skill to your local

Skill Files