Vitals
Read-only macOS performance inspection: a deterministic CLI gathers the numbers, Interpretation.md turns them into a diagnosis instead of a data dump.
Customization
Before executing, check for user customizations at:
~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Vitals/
If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.
Voice Notification
When executing a workflow, do BOTH:
Send voice notification:
curl -s -X POST http://localhost:31337/notify \
-H "Content-Type: application/json" \
-d '{"message": "Running WORKFLOWNAME in Vitals"}' \
> /dev/null 2>&1 &
Output text notification: Running **WorkflowName** in **Vitals**...
Workflow Routing
| Workflow |
Trigger |
File |
| HealthCheck |
"how's my system", "check my mac", "system health" |
Workflows/HealthCheck.md |
| FindCulprit |
"mac is slow", "what's eating CPU/GPU/memory", "fans loud" |
Workflows/FindCulprit.md |
| DeepDiagnosis |
"full diagnosis", "deep check", chronic/recurring slowness |
Workflows/DeepDiagnosis.md |
Interpretation reference (load with any workflow): Interpretation.md — thresholds, known-process table, diagnosis shape.
Quick Reference
bun ~/.claude/skills/Vitals/Tools/Vitals.ts check # fast snapshot (<1s)
bun ~/.claude/skills/Vitals/Tools/Vitals.ts hogs # live per-process CPU/energy (~3s)
bun ~/.claude/skills/Vitals/Tools/Vitals.ts full # everything (~4s)
# also: gpu · memory · disk · thermal · startup · --json · --top N
The tool is read-only by contract: it never kills, renices, unloads, or writes system state. Remediation is recommended to the operator, never executed by the skill.
Examples
Example 1: Something feels slow
User: "My Mac is dragging, what's going on?"
→ FindCulprit: run hogs + check + gpu
→ Cross-reference Interpretation.md (is the hog a known background process?)
→ Report: named culprit with two evidence classes, recommended action for approval
Example 2: Routine check
User: "How's my system doing?"
→ HealthCheck: run check
→ One-screen verdict: 🟢/🟡/🔴 per subsystem, abnormalities flagged against thresholds
Example 3: Fans blasting
User: "Why are my fans so loud?"
→ FindCulprit: thermal + hogs + gpu
→ If kernel_task is the top consumer: that IS the cooling response — report the thermal cause, not the process
Gotchas
top's first sample is garbage — CPU% is cumulative since boot. The tool always runs -l 2 and parses the SECOND sample; never "optimize" this away.ps -m does not reliably sort by memory on modern macOS (observed mis-ordering by GB-scale RSS). The tool sorts in code; keep it that way.kernel_task high CPU is the thermal system working, not a runaway process — it pins cores to force cooling. Never recommend killing it.- macOS "used" memory is not a problem signal. Free RAM is deliberately spent on cache;
kern.memorystatus_vm_pressure_level (1 normal / 2 warning / 4 critical) and live swapouts are the real signals.
powermetrics requires sudo and runs forever without -n. It's the only accurate source of per-process energy and GPU power — keep it as the optional consent-gated leg in DeepDiagnosis.top -l truncates command names (~16 chars) regardless of COLUMNS in logging mode. Use the PID to identify the full process (ps -p <pid> -o comm=).- GPU via
ioreg -c IOAccelerator works without sudo on Apple Silicon (Device Utilization % in PerformanceStatistics) but is not guaranteed on every GPU — the tool degrades to an explicit unavailable-message, never a silent blank.
pmset -g therm may not report CPU_Speed_Limit on desktops — the tool treats a missing key as not-throttled rather than erroring.
1---2name: vitals3description: macOS system performance diagnostics — see how the machine is running and what's slowing it down: CPU/GPU/memory/energy hogs, thermal throttling, memory and swap pressure, disk usage, Spotlight indexing, launchd/startup load, via a deterministic read-only CLI with known-process interpretation (kernel_task, WindowServer, mds_stores). USE WHEN mac slow, system slow, what's slowing down my mac, computer is slow, what's eating CPU, CPU usage, GPU usage, what's using the GPU, memory pressure, RAM usage, swap, runaway process, fans loud, mac running hot, thermal throttling, system health, check my mac, how's my system running, top processes, energy hogs, activity monitor, startup items, launch agents load, system taxed. NOT FOR network/wifi diagnostics, website or deployed-app health monitoring, or security scanning.4---5
6# Vitals
7
8Read-only macOS performance inspection: a deterministic CLI gathers the numbers, `Interpretation.md` turns them into a diagnosis instead of a data dump.
9
10## Customization
11
12**Before executing, check for user customizations at:**
13`~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/Vitals/`
14
15If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.
16
17## Voice Notification
18
19**When executing a workflow, do BOTH:**
20
211. **Send voice notification**:
22 ```bash
23 curl -s -X POST http://localhost:31337/notify \
24 -H "Content-Type: application/json" \
25 -d '{"message": "Running WORKFLOWNAME in Vitals"}' \
26 > /dev/null 2>&1 &
27 ```
28
292. **Output text notification**: `Running **WorkflowName** in **Vitals**...`
30
31## Workflow Routing
32
33| Workflow | Trigger | File |
34|----------|---------|------|
35| **HealthCheck** | "how's my system", "check my mac", "system health" | `Workflows/HealthCheck.md` |
36| **FindCulprit** | "mac is slow", "what's eating CPU/GPU/memory", "fans loud" | `Workflows/FindCulprit.md` |
37| **DeepDiagnosis** | "full diagnosis", "deep check", chronic/recurring slowness | `Workflows/DeepDiagnosis.md` |
38
39**Interpretation reference (load with any workflow):** `Interpretation.md` — thresholds, known-process table, diagnosis shape.
40
41## Quick Reference
42
43```bash
44bun ~/.claude/skills/Vitals/Tools/Vitals.ts check # fast snapshot (<1s)
45bun ~/.claude/skills/Vitals/Tools/Vitals.ts hogs # live per-process CPU/energy (~3s)
46bun ~/.claude/skills/Vitals/Tools/Vitals.ts full # everything (~4s)
47# also: gpu · memory · disk · thermal · startup · --json · --top N
48```
49
50The tool is read-only by contract: it never kills, renices, unloads, or writes system state. Remediation is recommended to the operator, never executed by the skill.
51
52## Examples
53
54**Example 1: Something feels slow**
55```
56User: "My Mac is dragging, what's going on?"
57→ FindCulprit: run hogs + check + gpu
58→ Cross-reference Interpretation.md (is the hog a known background process?)
59→ Report: named culprit with two evidence classes, recommended action for approval
60```
61
62**Example 2: Routine check**
63```
64User: "How's my system doing?"
65→ HealthCheck: run check
66→ One-screen verdict: 🟢/🟡/🔴 per subsystem, abnormalities flagged against thresholds
67```
68
69**Example 3: Fans blasting**
70```
71User: "Why are my fans so loud?"
72→ FindCulprit: thermal + hogs + gpu
73→ If kernel_task is the top consumer: that IS the cooling response — report the thermal cause, not the process
74```
75
76## Gotchas
77
78- **`top`'s first sample is garbage** — CPU% is cumulative since boot. The tool always runs `-l 2` and parses the SECOND sample; never "optimize" this away.
79- **`ps -m` does not reliably sort by memory** on modern macOS (observed mis-ordering by GB-scale RSS). The tool sorts in code; keep it that way.
80- **`kernel_task` high CPU is the thermal system working**, not a runaway process — it pins cores to force cooling. Never recommend killing it.
81- **macOS "used" memory is not a problem signal.** Free RAM is deliberately spent on cache; `kern.memorystatus_vm_pressure_level` (1 normal / 2 warning / 4 critical) and live swapouts are the real signals.
82- **`powermetrics` requires sudo and runs forever without `-n`.** It's the only accurate source of per-process energy and GPU power — keep it as the optional consent-gated leg in DeepDiagnosis.
83- **`top -l` truncates command names** (~16 chars) regardless of COLUMNS in logging mode. Use the PID to identify the full process (`ps -p <pid> -o comm=`).
84- **GPU via `ioreg -c IOAccelerator` works without sudo on Apple Silicon** (`Device Utilization %` in PerformanceStatistics) but is not guaranteed on every GPU — the tool degrades to an explicit unavailable-message, never a silent blank.
85- **`pmset -g therm` may not report `CPU_Speed_Limit` on desktops** — the tool treats a missing key as not-throttled rather than erroring.
danielmiessler