✓ Verified 💻 Development ✓ Enhanced Data

System Watchdog

System resource monitoring that detects wasteful or suspicious processes.

Rating: 4.9 (328 reviews)
Downloads: 2,955 downloads
Version: 1.0.0

Overview

System resource monitoring that detects wasteful or suspicious processes.

Complete Documentation

View Source →

System Watchdog

Monitor system resources and flag wasteful or suspicious processes. Works standalone as a bash script — see openclaw.md for scheduled cron setup.

Standalone Usage

Run the check script directly — no OpenClaw required:

bash

bash check.sh

Outputs a JSON object to stdout. Parse it however you like — pipe to jq, feed to an agent, integrate into your own monitoring stack.

Output Format

json

{
  "suspicious": true,
  "summary": {
    "ram": "12.3/31.2 GB (39%)",
    "swap": "0.5/8.0 GB (6%)",
    "load": "1.2/0.8/0.6",
    "cores": 8,
    "disk": "120/256 GB (45%)"
  },
  "issues": [
    {
      "type": "high_ram",
      "description": "claude (PID 1234) 4650MB RAM",
      "details": { "pid": 1234, "name": "claude", "cpu_pct": 2.1, "mem_mb": 4650, "elapsed": "3d" }
    }
  ],
  "top_processes": [
    { "pid": 1234, "name": "claude", "cpu_pct": 2.1, "mem_mb": 4650, "elapsed": "3d" }
  ]
}

suspicious: true → at least one issue exceeded a threshold
suspicious: false → system looks healthy

Thresholds

Check	Threshold	Issue Type
Process RAM	> 4096 MB	high_ram
Process CPU	> 50%	high_cpu
Stale processes	Running > 2 days AND using > 100 MB or > 1% CPU	stale
Disk usage	> 80% on root mount	disk

Common Offenders

claude / codex — AI coding agents left running for days
whisper / whisper-server — speech-to-text servers consuming GPU/RAM
python / python3 — runaway scripts or leaked processes
node — dev servers or builds that never stopped

Agent Workflow (for AI agents)

Run check.sh
Parse the JSON output
If suspicious is false → do nothing (no report needed)
If suspicious is true → format a concise report and notify the user

Suggested Report Format

text

⚠️ System Watchdog Report

📊 System: RAM 12.3/31.2 GB (39%) | Swap 0.5/8.0 GB (6%) | Load 1.2/0.8/0.6
💾 Disk: / 45% (120/256 GB)

🔴 Issues Found:

HIGH RAM — claude (PID 1234)
  CPU: 2.1% | RAM: 4650 MB | Running: 3 days
  → Likely stale, safe to kill

💡 Suggested: kill 1234

Platform Notes

macOS only — check.sh uses sysctl, vm_stat, and macOS ps flags. It won't work on Linux without adaptation (replace with free, /proc/meminfo, etc.).
Intermittent jq-style parse error — the script occasionally fails on first run due to a race in process scanning. Retry once before reporting failure.

Installation

Terminal bash


openclaw install system-watchdog

Copied!

💻Code Examples

bash check.sh

bash-checksh.txt

Outputs a JSON object to stdout. Parse it however you like — pipe to `jq`, feed to an agent, integrate into your own monitoring stack.

### Output Format

}

.txt

- `suspicious: true` → at least one issue exceeded a threshold
- `suspicious: false` → system looks healthy

### Thresholds

| Check | Threshold | Issue Type |
|-------|-----------|------------|
| Process RAM | > 4096 MB | `high_ram` |
| Process CPU | > 50% | `high_cpu` |
| Stale processes | Running > 2 days AND using > 100 MB or > 1% CPU | `stale` |
| Disk usage | > 80% on root mount | `disk` |

### Common Offenders

- `claude` / `codex` — AI coding agents left running for days
- `whisper` / `whisper-server` — speech-to-text servers consuming GPU/RAM
- `python` / `python3` — runaway scripts or leaked processes
- `node` — dev servers or builds that never stopped

## Agent Workflow (for AI agents)

1. Run `check.sh`
2. Parse the JSON output
3. If `suspicious` is `false` → do nothing (no report needed)
4. If `suspicious` is `true` → format a concise report and notify the user

### Suggested Report Format

example.json

{
  "suspicious": true,
  "summary": {
    "ram": "12.3/31.2 GB (39%)",
    "swap": "0.5/8.0 GB (6%)",
    "load": "1.2/0.8/0.6",
    "cores": 8,
    "disk": "120/256 GB (45%)"
  },
  "issues": [
    {
      "type": "high_ram",
      "description": "claude (PID 1234) 4650MB RAM",
      "details": { "pid": 1234, "name": "claude", "cpu_pct": 2.1, "mem_mb": 4650, "elapsed": "3d" }
    }
  ],
  "top_processes": [
    { "pid": 1234, "name": "claude", "cpu_pct": 2.1, "mem_mb": 4650, "elapsed": "3d" }
  ]
}

example.txt

⚠️ System Watchdog Report

📊 System: RAM 12.3/31.2 GB (39%) | Swap 0.5/8.0 GB (6%) | Load 1.2/0.8/0.6
💾 Disk: / 45% (120/256 GB)

🔴 Issues Found:

HIGH RAM — claude (PID 1234)
  CPU: 2.1% | RAM: 4650 MB | Running: 3 days
  → Likely stale, safe to kill

💡 Suggested: kill 1234