mcpField
S
system-watchdog

system-watchdog

github.com/tychohqCloud & DevOps092 installsUpdated 30w ago
Repository

About system-watchdog

system-watchdog is a macOS bash script for checking resource usage and flagging suspicious or wasteful processes. Its JSON output can be parsed by agents or monitoring workflows, and it can run standalone or on a cron schedule.

Key features

  1. 01Checks RAM, swap, load, cores, and disk
  2. 02Flags high-resource and stale processes
  3. 03Reports threshold issues as JSON
  4. 04Runs standalone with bash check.sh

Use cases

  1. 01Inspect resource usage on a macOS system
  2. 02Identify long-running or high-usage processes
  3. 03Feed system checks into an agent or monitoring stack

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/tychohq/agent-skills --skill system-watchdog

After installing, type/system-watchdogin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

check.sh
openclaw-cron.json
OPENCLAW.md

Details

From the project README

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 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
{
  "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
CheckThresholdIssue Type
Process RAM> 4096 MBhigh_ram
Process CPU> 50%high_cpu
Stale processesRunning > 2 days AND using > 100 MB or > 1% CPUstale
Disk usage> 80% on root mountdisk
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
⚠️ 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.

Comments

Markdown supported