Watchdog — Agent Self-Monitoring & Health Alerts

The Problem

Most agent failures are silent. Your agent gets stuck in a loop burning tokens, hallucinates past a blocker, or crashes without telling you. You find out hours later when you check your API bill.

The Solution

Watchdog is a drop-in monitoring layer with both internal (agent self-assessment) and external (scripts) monitoring:

What It Monitors

• Loop detection — Catches repeated tool call patterns before they burn money
• Cost awareness — Token tracking with budget caps and 50%/80%/100% alerts
• Stuck detection — Dead man's switch fires if agent goes silent
• Quality drift — Agent enters "cautious mode" (confirms before acting) when metrics degrade
• Heartbeat pings — Regular status updates to operator

Alert Levels

• 🟢 Working on task X. $0.42 spent. 12 min elapsed.
• 🟡 Possible loop — repeated web_search 4x with similar queries.
• 🔴 Budget 80% consumed. Pausing for approval.
• ⚫ No activity for 15 min. Agent may be stuck.

What's Included

• watchdog.md — Core self-monitoring protocol (drop into agent context)
• HEARTBEAT.md — Scheduled heartbeat task definition
• health-check.sh — External health monitor (runs without LLM, costs $0)
• alert.sh — Multi-channel alert dispatcher (Slack/Discord webhooks)
• setup.md — 5-minute installation guide