Written for the person who just installed it and wants to know what the circles mean. Fifteen minutes end to end; skip to whatever you need.
Getting started
Open the DMG and drag Mac Vitals across. The first launch may ask you to confirm — the build is notarized by Apple, so you should not see a Gatekeeper block.
There is no Dock icon and no main window. Mac Vitals is an accessory app: it lives entirely in the menu bar. Look for the waveform widgets near the clock.
The first run offers permission cards and a hardware scan that detects Ollama, LM Studio, Docker and any dev servers you have running. Every step is skippable and nothing is requested silently.
Settings ▸ Menu Bar. Add a slot per module, pick its style, drag to reorder. The preview above the list is the real widget renderer, not a mockup.
Reading the menu bar
Each slot renders one module in whichever style suits it. Hover any widget for a spoken-quality summary; VoiceOver reads the same sentence.
Clicking opens the dropdown scoped to that module. Click the GPU widget and you get the GPU card, not eleven cards to scan. The header offers All modules to widen; ⌥⌘V always opens the full list. Clicking a different widget while the panel is open re-scopes it in place rather than closing.
Menu bar refresh rate is a setting, not a hidden constant, and it is labelled with its real cost: Live (1 s) ≈ 2% of one core, Balanced (2 s, the default) ≈ 1.3% with a live sparkline and ≈ 0.3% without, Efficient (5 s) ≈ 0.85%.
The reason is worth knowing: macOS re-snapshots a menu bar item's entire button into bitmaps on every visual change, roughly 12 ms each, regardless of how little changed. So the cost tracks how often your numbers change, not how much monitoring happens. A widget whose displayed value is unchanged is free.
The modules
~/.macvitals/remotes.yaml, polled over SSH with no agent to install.Alerts & insights
A rule is WHEN metric OP value FOR duration THEN actions. The FOR matters: a threshold crossed for one sample is noise, and a rule only counts continuous samples, so a gap resets the clock rather than quietly accumulating.
Five templates ship with the app: LLM tok/s dropping more than 15% from baseline, container restart loops, free disk under 50 GB, a new process listening on any port, and CPU temperature above 95°C for five minutes. Test actions once fires a rule on demand so you can validate a webhook without waiting for the real condition.
Insights come from a per-metric baseline bucketed by hour of day, so 90% CPU at 03:00 is not judged against 90% CPU during your afternoon build. An anomaly is a sustained move beyond three times the median absolute deviation, and every card carries a cause, the evidence, and at least one action. There are no dead-end alerts by design.
A cold bucket falls back to the metric-wide baseline, which is what makes the engine useful on the day you install it rather than silent for a week.
Permissions
Mac Vitals never raises a permission prompt behind your back. Everything below is requested from an onboarding card that explains what it buys, and the app works without any of it.
Your data
None of it is uploaded. See the privacy policy for the long version.
Keyboard
Every chart has a VoiceOver summary of the form “CPU 43 percent, rising, peaked 89 percent two minutes ago”, and Reduce Motion turns springs into crossfades throughout.