machealth
npx machina-cli add skill lu-zhengda/macos-toolkit/machealth --openclawmachealth — macOS System Health Checker
Run a one-shot health assessment:
!machealth --human 2>&1 || echo "machealth not installed — brew install lu-zhengda/tap/machealth"
Analyze the output above. Report the overall health score and status (green/yellow/red). Flag any subsystems that are degraded or critical. Offer to run machealth diagnose --human for actionable recommendations or machealth watch --human for continuous monitoring.
Commands
| Command | Purpose | Example |
|---|---|---|
machealth | One-shot health assessment (JSON) | machealth |
machealth check | Same as default (explicit) | machealth check |
machealth --human | Human-readable health report | machealth --human |
machealth diagnose | Health check with actionable recommendations (JSON) | machealth diagnose |
machealth diagnose --human | Human-readable diagnose output | machealth diagnose --human |
machealth watch | Continuous monitoring (JSON Lines) | machealth watch --interval 10s |
machealth watch --human | Live terminal dashboard | machealth watch --human |
Monitored Subsystems
| Subsystem | Weight | Metrics |
|---|---|---|
| CPU | 20% | Load averages, per-core utilization |
| Memory | 25% | Memory pressure, swap usage |
| Thermal | 20% | CPU speed limit, throttling detection |
| Disk | 15% | Available space, usage percentage |
| Battery | 10% | Charge level, power source, health |
| iCloud | 5% | Sync status |
| Network | 5% | Reachability, active interface |
| Time Machine | 0% | Backup state (informational only) |
Exit Codes
| Code | Status | Score Range |
|---|---|---|
| 0 | Healthy (green) | 80-100 |
| 1 | Degraded (yellow) | 50-79 |
| 2 | Critical (red) | 0-49 |
JSON Output
All commands output JSON by default. Use --human for human-readable format:
machealth # JSON output
machealth --human # Human-readable output
machealth diagnose # JSON with recommendations
machealth diagnose --human # Human-readable recommendations
Safety Guidelines
- Read-only: All commands are non-destructive — they only read system metrics
- Low overhead: Health checks are lightweight and safe to run frequently
- Watch mode: Continuous monitoring exits cleanly on Ctrl+C
Source
git clone https://github.com/lu-zhengda/macos-toolkit/blob/main/skills/machealth/SKILL.mdView on GitHub Overview
machealth performs a one-shot health assessment on macOS, returning an overall health score and a green/yellow/red status. It flags degraded or critical subsystems and can provide actionable guidance via diagnose or continuous monitoring via watch. By default, outputs are JSON, with --human offering a readable report.
How This Skill Works
On invocation, machealth analyzes monitored subsystems (CPU, Memory, Thermal, Disk, Battery, iCloud, Network, Time Machine) and aggregates their metrics into a 0–100 health score with a color status. It supports JSON output by default and has modes for human-readable reports (--human), actionable recommendations (diagnose), and continuous monitoring (watch).
When to Use It
- When you want a quick, all-in-one health snapshot after suspecting performance issues
- To verify CPU load, memory pressure, thermal throttling, or disk space health
- To confirm iCloud sync status or Time Machine backup state
- When diagnosing system issues and identifying degraded or critical subsystems
- For ongoing monitoring with machealth watch for proactive maintenance
Quick Start
- Step 1: Run machealth to get a one-shot health assessment (default JSON)
- Step 2: If the score is not green, run machealth diagnose for actionable recommendations
- Step 3: For ongoing visibility, start machealth watch --human or machealth watch --interval <seconds>
Best Practices
- Run machealth first to establish a baseline health score
- Use machealth --human for quick interpretation and triage
- If a subsystem is degraded or critical, run machealth diagnose for actionable guidance
- Combine with watch for continuous monitoring on mission-critical Macs
- Keep backups and power sources consistent; watch will reflect changes in real-time
Example Use Cases
- machealth outputs a JSON object with score and status when you run it
- machealth --human presents a readable health report highlighting degraded subsystems
- machealth diagnose provides JSON with recommendations
- machealth watch --human runs a live dashboard
- machealth watch --interval 10s runs continuous checks with a 10-second cadence
