Proactive system monitoring with 7 collectors, alerting, and Telegram notifications
<Use_When>
<Do_Not_Use_When>
df -h, top -l 1)<Why_This_Exists> Developers often miss slow-building problems: disk filling up, memory leaks in dev servers, failing CI pipelines they forgot about, new Sentry errors from last night's deploy, or calendar conflicts for upcoming meetings. Without proactive monitoring, these issues become emergencies. Heartbeat runs collectors on a schedule (or on-demand), evaluates against thresholds, and pushes alerts to Telegram so the developer knows about problems even when they are away from the terminal. It provides the "ops awareness" that solo developers lack. </Why_This_Exists>
<Execution_Policy>
Collector 1 - System Metrics:
top -l 1 -s 0 | head -12 for CPU and memorydf -h / for disk usageuptime for load average and uptimesysctl hw.memsize for total memoryCollector 2 - Dev Environment:
node --version, npm --version, python3 --versiongit status --porcelain | wc -l for uncommitted changesnpm test 2>&1 | tail -5 or project test command (if configured)npx tsc --noEmit 2>&1 | tail -10 for TypeScript errorsCollector 3 - GitHub CI:
gh run list --limit 5 --json status,conclusion,name,createdAtgh pr list --json number,title,mergeable,reviewsCollector 4 - Sentry Errors:
curl -s -H "Authorization: Bearer $SENTRY_AUTH_TOKEN" "https://sentry.io/api/0/projects/$SENTRY_ORG/$SENTRY_PROJECT/issues/?query=is:unresolved&limit=5"Collector 5 - Calendar:
tell application "Calendar" to get summary of events of calendar "Work" whose start date >= (current date) and start date <= ((current date) + 1 * days)Collector 6 - Process Health:
ps aux | head -20 sorted by CPU usagelsof -i -P | grep LISTEN for open portsCollector 7 - Custom Collectors:
~/superclaw/collectors/{"status":"ok|warn|critical","metric":value,"message":"..."}Phase 2 - Evaluate Against Thresholds: Compare collected metrics to alert rules
| Metric | Warning | Critical |
|---|---|---|
| CPU % | > 70% | > 90% |
| Memory % | > 75% | > 90% |
| Disk % | > 80% | > 95% |
| Load Average | > 4.0 | > 8.0 |
| Uncommitted Files | > 20 | > 50 |
| Failed CI Runs | >= 1 | >= 3 |
| Unresolved Sentry | >= 5 | >= 20 |
| TypeScript Errors | >= 1 | >= 10 |
Phase 3 - Generate Report: Format results into a structured heartbeat report
=== SuperClaw Heartbeat ===
Time: 2026-02-12 10:30:00
Overall: OK | WARN | CRITICAL
[System]
CPU: 23% (ok) | Memory: 61% (ok) | Disk: 45% (ok)
Load: 1.2 | Uptime: 14d 3h
[Dev Environment]
Node: v22.1.0 | TypeScript Errors: 0 (ok)
Uncommitted: 3 files | Tests: passing
[GitHub CI]
Last 5 runs: 4 passed, 1 failed
Open PRs: 2 (1 needs review)
[Sentry]
Unresolved: 3 issues (warn)
Top: "TypeError: Cannot read property 'id' of undefined" (12 events)
[Calendar]
14:00 - Team standup (30min)
16:00 - Design review (1hr)
[Processes]
Top CPU: node (8.2%), postgres (3.1%), docker (2.4%)
Listening: :3000 (node), :5432 (postgres), :6379 (redis)
[Alerts]
WARN: 1 failed CI run on main branch
WARN: 3 unresolved Sentry issues
Phase 4 - Alert on Critical/Warn: Send notifications for threshold violations
sc_send_messagePhase 5 - Send to Telegram (if configured):
sc_send_message with channel="telegram"Phase 6 - Store Results for Trending:
~/superclaw/heartbeat/history/YYYY-MM-DD-HH-mm.jsonPhase 7 - Schedule Next Run (if periodic monitoring requested):
crontab -l
</Steps>
<Tool_Usage> Messaging (2 tools):
sc_telegram_status -- Check if Telegram bot is configured before attempting alerts; no paramssc_send_message -- Send heartbeat report or alert to Telegram; params: channel (string, "telegram"), text (string, formatted report/alert)Scheduling:
Bash -- Manage system crontab via crontab -l, crontab -e, crontab <file> for scheduling periodic heartbeat runsSystem Data (via Bash):
top -l 1 -s 0 | head -12 -- CPU and memory usage snapshotdf -h / -- Disk usage for root volumeuptime -- System uptime and load averagesps aux --sort=-%cpu | head -10 -- Top CPU-consuming processeslsof -i -P | grep LISTEN -- Listening network portsGitHub Data (via Bash with gh CLI):
gh run list --limit 5 --json status,conclusion,name,createdAt -- Recent CI runsgh pr list --json number,title,mergeable -- Open pull requestsCalendar Data (via SuperClaw):
sc_osascript -- Query Calendar.app via AppleScript for today's eventsNotification Fallback:
sc_notify -- Send macOS notification if Telegram is unavailable; params: title, message
</Tool_Usage><Escalation_And_Stop_Conditions>
<Final_Checklist>
Heartbeat configuration in ~/superclaw/superclaw.json: