| name | mac-health |
| description | Mac system monitoring skill. Returns CPU, memory, temperature, disk, and Docker status.
Trigger when:
- "How's the Mac?" or "How's the server?"
- "System status" or "Server status"
- "Check server health" or "Mac health"
- "What's eating CPU?" or "What's using memory?"
- "Disk space?" or "Storage status?"
- "Temperature?" or "Is the Mac hot?"
- "Docker containers?" or "Are containers running?"
- Any question about Mac hardware health or resource usage
|
Experimental Feature
This skill has been tested on Mac Mini M4 Pro. Other Mac models may require customization.
If metrics aren't working, ask Claude to adjust the commands for your hardware.
mac-health — System Monitoring Skill
Check Mac system health with a single command. Returns CPU, memory, temperature, disk, and Docker status.
Triggers
Use this skill when user asks:
- "How's the Mac?"
- "System status" / "Server status"
- "Check server health"
- "What's eating CPU?"
- "Disk space?" / "Storage status?"
- "Temperature?"
- "Docker containers?"
How to Use
Quick Mode (default, ~2s)
python $WORKING_DIR/scripts/mac-health-collector.py --table
Collects: CPU %, RAM, memory pressure, SSD temperature, disk health/space, external disks, Docker containers, top processes.
Deep Mode (~5s, includes E/P cores + GPU)
python $WORKING_DIR/scripts/mac-health-collector.py --deep --table
Adds: E-cluster/P-cluster residency, CPU power (mW), GPU utilization, GPU power.
Note: Deep mode uses sudo powermetrics internally. Requires passwordless sudo setup for /usr/bin/powermetrics.
Output Formats
| Flag | Output |
|---|
--table | Human-readable table (recommended) |
--pretty | Formatted JSON |
| (none) | Compact JSON |
Interpreting Results
Overall Status
| Status | Meaning |
|---|
healthy | All metrics normal |
warn | One or more warnings (see warnings array) |
critical | Critical issue detected |
Warning Thresholds
| Metric | Warning | Critical |
|---|
| SSD temperature | >=60C | >=70C |
| Disk usage | >=80% | >=90% |
| Memory pressure | "warn" | "critical" |
Key Metrics Explained
CPU (quick mode):
total_used_percent — Overall CPU usage (user + system)- 100%+ is normal with VMs (Virtualization.framework uses multiple cores)
CPU (deep mode):
e_cluster_active_percent — Efficiency cores usagep_cluster_active_percent — Performance cores usagecpu_power_mw — Total CPU power draw in milliwatts
Memory:
pressure — macOS memory pressure: nominal, warn, critical- More meaningful than raw usage percentage
Temperature:
- Uses SSD temperature as proxy (Apple restricts CPU temp on M-series)
- 40-55C = normal, 55-60C = warm, 60-70C = warning, 70+ = critical
Disk:
health — SMART status: PASSED or FAILEDwear_percent — SSD wear level (0% = new)data_written_tb — Lifetime data written
Docker:
- Lists running containers with status
- "healthy" in status means container health checks passing
Presenting Results
After running the collector, always add analysis. Don't just dump the table.
Structure
- Show the table output (raw from collector)
- Add "Analysis" section with:
- Overall verdict (1 sentence)
- Notable observations (what stands out)
- Context for high values (explain WHY, not just WHAT)
- Recommendations if any issues
What to Comment On
| Metric | Comment when... |
|---|
| CPU >80% | Identify the culprit process, explain if expected (VM, ML workload) |
| CPU power >25W | Note it's running hot, check if sustained |
| E-cores maxed, P-cores idle | Efficiency mode, normal for background tasks |
| P-cores maxed | Heavy workload, check what's running |
| Memory >75% | Note if pressure is still nominal (macOS handles this well) |
| Memory pressure warn/critical | This is the real problem, not raw % |
| SSD >55C | Getting warm, note if under heavy I/O |
| SSD wear >5% | Starting to show age, estimate remaining life |
| Docker unhealthy | Flag which container(s), suggest checking logs |
| External disk missing | Compare to expected count if known |
Example Analysis
**Analysis:**
System healthy. The 97% CPU is entirely from Virtualization.framework
running Colima — that's your Docker VM, expected behavior with ML
processing.
Memory at 80% but pressure is nominal — macOS is using RAM efficiently,
no swapping. SSD cool at 53C despite the workload.
All 4 containers healthy and running for 3 hours — stable deployment.
No action needed.
Tone
- Direct, concise
- Explain the "why" behind numbers
- Don't alarm about expected behavior (VM CPU usage, high memory with nominal pressure)
- Flag actual concerns clearly
Troubleshooting
| Issue | Solution |
|---|
smartctl failed | Install: brew install smartmontools |
| Deep mode errors | Check sudoers: sudo visudo -f /etc/sudoers.d/powermetrics |
| No temperature | Normal for external USB drives |
| Docker unavailable | Docker/Colima not running |
Customization
This skill was developed on Mac Mini M4 Pro. If you're on different hardware:
- Temperature sensors — Sensor names vary by model. Run
sudo powermetrics --samplers smc -n 1 to see available sensors on your machine.
- GPU metrics — Not all Macs report GPU the same way.
- Docker — Only relevant if you run Docker.
Ask Claude to adjust the script for your specific Mac model.
Files
- Collector:
$WORKING_DIR/scripts/mac-health-collector.py
- Skill:
.claude/skills/mac-health/SKILL.md
