system-health

name	system-health
description	>-

System Health Check

Collect hardware metrics via hwinfo-bridge (primary, full HWiNFO sensor data from Windows host) and hwinfo-linux (supplementary, local Linux/WSL2 metrics), detect anomalies against known thresholds, and compare with historical data to surface trends.

Inputs

• $categories: Optional comma-separated list of metric categories to check (e.g. cpu_temps,gpu,memory). If omitted, collect all available categories.

Goal

Produce a clear, actionable health report covering current sensor readings, anomaly flags with severity levels, and trend comparison against previous runs.

Steps

1. Ensure hwinfo-linux and hwinfo-bridge Are Available

The repo contains two binaries: hwinfo-linux (local Linux sensors) and hwinfo-bridge (RemoteHWInfo bridge to Windows HWiNFO). Both are needed for full coverage.

Check if they are on PATH:

command -v hwinfo-linux && command -v hwinfo-bridge

If not found:

1. Check if the repo already exists at ~/.local/src/hwinfo-linux/
2. If not, clone it: git clone --recurse-submodules https://github.com/coffeegrind123/hwinfo-linux.git ~/.local/src/hwinfo-linux
3. Build: cd ~/.local/src/hwinfo-linux && make
4. Install: sudo make install — if sudo is unavailable, use the binaries directly from the build directory and set HWINFO_BIN_DIR=~/.local/src/hwinfo-linux

Verify both binaries exist:

ls -la $HWINFO_BIN_DIR/hwinfo-linux $HWINFO_BIN_DIR/hwinfo-bridge

Success criteria: Both hwinfo-linux and hwinfo-bridge binaries are executable.

2. Collect Metrics

There are two binaries in the hwinfo-linux repo — use BOTH:

• hwinfo-bridge — connects to the RemoteHWInfo HTTP endpoint on the Windows host (default: http://host.docker.internal:60000/json.json). This provides the full HWiNFO sensor set: CPU/GPU/chipset/VRM temperatures, voltages, fan speeds, power draw, SMART, clocks, per-core usage, etc. This is the primary data source.
• hwinfo-linux — reads local Linux sensors (procfs, sysfs, hwmon). Provides WSL2-side memory (physical + swap), per-core CPU usage from the Linux scheduler perspective, and disk I/O stats. This is the supplementary data source for OS-level metrics the bridge cannot see.

Collection order:

1. Try the bridge first:

$HWINFO_BIN_DIR/hwinfo-bridge -p

If it returns valid JSON with sensor data, this is the primary dataset. If the bridge endpoint is unreachable (connection refused, timeout), warn the user that bridge data is unavailable and note that only local Linux sensors will be used.

2. Always also run local collection:

$HWINFO_BIN_DIR/hwinfo-linux -p

# Or filtered categories (if $categories provided)
$HWINFO_BIN_DIR/hwinfo-linux -c $categories -p

3. Merge both datasets for the report. The bridge provides the authoritative hardware sensor readings (temperatures, voltages, fans, power, GPU, SMART). The local tool provides WSL2 memory/swap stats, Linux-side CPU usage, and disk I/O counters. Where both report the same metric (e.g. CPU usage), present both and label which source each comes from.

Use hwinfo-linux -l to list available local categories if the user's requested category is not recognized.

Success criteria: Bridge data captured (or explicit warning if bridge is down) AND local Linux data captured. At minimum, one source must produce valid JSON.

3. Analyze and Detect Anomalies

Parse the JSON output and flag values that exceed these thresholds:

Temperature (°C):

Severity	CPU Package/Core	GPU	Disk/NVMe	Chipset
Warning	>80	>85	>55	>70
Critical	>95	>100	>70	>90

Memory:

• Warning: Available memory <10% of total
• Critical: Available memory <5% of total

Storage (SMART):

• Warning: Any SMART attribute flagged as degraded
• Critical: SMART overall health status not "PASSED"

GPU:

• Warning: Memory usage >85%, thermal throttling active
• Critical: Memory usage >95%, error counts increasing

General:

• Flag any metric where current exceeds max from previous readings by >20%
• Flag any sensor returning error or null values

For each anomaly, record: category, metric name, current value, threshold, severity level.

Success criteria: All metrics evaluated against thresholds. Anomaly list produced (may be empty if system is healthy).

4. Compare with Historical Data

Historical logs are stored at ~/.local/share/system-health/.

Read previous run:

ls -t ~/.local/share/system-health/*.json 2>/dev/null | head -1

If a previous log exists:

• Compare current values against the previous run's values
• Flag significant changes: temperature deltas >10°C, memory usage swings >15%, new SMART warnings
• Note trends: "CPU temp trending up over last N runs" if 3+ logs show consistent increase

Save current run:

mkdir -p ~/.local/share/system-health

Write the current JSON output plus anomaly metadata to ~/.local/share/system-health/YYYY-MM-DDTHH-MM-SS.json.

Keep a maximum of 50 historical logs. Delete oldest files if over limit.

Success criteria: Current data saved. Comparison completed if prior data existed.

5. Report Findings

Present a structured report to the user:

Format:

## System Health Report — <timestamp>

### Overall Status: [HEALTHY | WARNING | CRITICAL]

### Summary
- <N> metrics collected across <M> categories
- <X> anomalies detected (<W> warnings, <C> critical)
- Trend: <comparison summary or "First run — no historical data">

### Anomalies (if any)
| Severity | Category | Metric | Current | Threshold | Trend |
|----------|----------|--------|---------|-----------|-------|
| ...      | ...      | ...    | ...     | ...       | ...   |

### Category Breakdown
For each category, show key metrics with current/min/max/avg values.
Highlight any values near thresholds in the breakdown.

Overall status is the highest severity found: CRITICAL > WARNING > HEALTHY.

If no anomalies, confirm system is healthy and show key metrics summary.

Success criteria: User receives a clear, actionable health report with severity-ranked anomalies and trend data.