Skip to content

v0.1.0 Release Notes

Release Date: 2026-07-13

WorkloadGuard is a macOS system health daemon that detects and mitigates runaway processes. This initial release provides comprehensive monitoring for excessive process spawning (common with AI coding assistants like Claude Code, Cursor, and Codex), high load conditions, and other resource exhaustion scenarios.

Highlights

  • Dual-trigger monitoring: Periodic checks plus immediate checks when load exceeds threshold
  • Cedar policy engine: Formal policy evaluation with composable rules
  • macOS native APIs: Direct libproc and sysctl bindings for efficient process enumeration
  • Prometheus metrics: Full observability with process, policy, and termination metrics

Features

Configuration

  • TOML-based configuration with custom Duration type for time intervals
  • Policy-based rules with process targeting, count thresholds, and conditional triggers
  • Parent process filtering to target specific process trees
  • Configurable actions: log, notify, terminate, diagnose, sample, spindump

Platform Integration

  • macOS libproc bindings via cgo for process enumeration
  • sysctl integration for load average, CPU count, and memory metrics
  • Native macOS notification support

Monitoring

  • Dual-trigger architecture: periodic timer + load threshold trigger
  • Process snapshot collection with parent name resolution
  • Cooldown tracking to prevent notification storms

Policy Engine

  • Cedar-based policy evaluation for formal decision making
  • Priority-ordered policy evaluation
  • Condition support: min_load1, min_load5, parent_process, exclude_parents

Diagnostics

  • Automatic capture of top, ps, and process tree before termination
  • Stack sampling for target PIDs
  • Timestamped diagnostic snapshots

Metrics

  • Prometheus metrics endpoint with custom registry
  • System metrics: load average, CPU count, memory
  • Process metrics: total count, count by name
  • Policy metrics: evaluations, triggers, actions
  • Termination metrics: SIGTERM and SIGKILL counts

CLI

  • workloadguard run - Start the daemon
  • workloadguard check - One-shot policy evaluation
  • workloadguard validate - Configuration validation
  • workloadguard version - Version information
  • Flags: --dry-run, --metrics, --metrics-addr, --config, --verbose

Installation

git clone https://github.com/plexusone/workloadguard.git
cd workloadguard
make install

Learn More

See README.md or the documentation site for full documentation including configuration examples, CLI reference, and architecture overview.