System Watchdog

---

name: system-watchdog

description: System resource monitoring. Detects actionable anomalies (memory pressure, runaway processes, disk pressure) and reports only when something needs attention. Optimized for few, high-signal alerts. Works on both Linux and macOS.

---

# System Watchdog

System watchdog for your machine. Detect real, actionable anomalies and stay quiet about normal steady-state conditions. Auto-detects Linux vs macOS.

Goal

Optimize for **few, high-signal alerts**.

Do **not** alert on:

Do alert on:

How to Invoke

bash ~/.openclaw/skills/system-watchdog/check.sh

The script outputs JSON to stdout. Parse the output and decide whether to report.

Override the state file path: `SYSTEM_WATCHDOG_STATE=/path/to/state.json`

Output Format

{
  "suspicious": true,
  "verdict": "watch|investigate|act_now|ok",
  "os": "Darwin|Linux",
  "summary": {
    "ram": "19.3/32.0 GB (60.4%)",
    "swap": "1.6/3.0 GB",
    "swap_delta": "+0.2 GB",
    "load": "3.30/2.21/2.17",
    "cores": 10,
    "disk": "14/926 GB (3%)",
    "available": "8.50 GB available",
    "free": "0.08 GB truly free",
    "inactive": "11.88 GB inactive/speculative",
    "compressed": "5.16 GB compressed"
  },
  "issues": [ ],
  "top_processes": [ ],
  "ignored_normals": [ ]
}

Note: `available` is Linux-only (MemAvailable). `free`, `inactive`, `compressed` are macOS-only (vm_stat breakdown).

Detection Philosophy

1. Memory pressure, not just RAM usage

High RAM usage alone is noisy. The script tracks **swap growth since last run** and low available/free memory as stronger signals. On macOS, high compressor usage with low free pages is also flagged.

2. Runaway behavior, not stale age

Never flag a process just because it has been running a long time. Look for memory growth (delta since last run) and sustained CPU instead.

3. Disk only when it matters

Ignore absolute disk usage. Only report disk when it is actually nearing a practical limit.

Agent Workflow

1. Run `check.sh`

2. Parse the JSON output

3. If `suspicious` is `false` → do nothing (no message)

4. If `suspicious` is `true` → format a concise report

5. Lead with the **verdict** and the 1–3 most important findings

Report Format

⚠️ System Watchdog — VERDICT

Why this matters:
- <1–3 concise findings from issues[].why>

Evidence:
- RAM <summary.ram>
- Swap <summary.swap> (<summary.swap_delta>)
- Load <summary.load>

Recommended:
- <issue suggested_action>

Ignored: process age, Docker baseline, disk absolute usage

Keep it short. Do **not** dump every top process unless it directly supports an issue.

State Tracking

The script persists lightweight state to `~/.openclaw/workspace/state/system-watchdog-state.json` so it can detect **changes since last run** (swap growth, per-process memory growth) rather than only snapshot values.