# Stats User Guide

**Stats** is a free, open-source macOS system monitor that lives in your menu bar. It shows live CPU, GPU, memory, disk, network, battery, sensor, Bluetooth, and clock information as compact widgets, and opens detailed pop-up panels when you click them. Everything runs locally on your Mac, and every monitor is fully configurable.

This guide walks you through installing Stats, turning monitors on, choosing how each one looks in the menu bar, reading the detail pop-ups, and tuning the app to your needs.

> [!NOTE]
> Stats is a menu bar utility — there is no main window that stays open. You interact with it almost entirely through the menu bar icons and the **Settings** window. If you ever lose track of it, open Settings (see [Opening Settings](#opening-settings)) and everything is there.

---

## Table of Contents

1. [Quick Start](#1-quick-start)
2. [Requirements](#2-requirements)
3. [Installation](#3-installation)
4. [Core Concepts](#4-core-concepts)
5. [Turning Monitors On and Off](#5-turning-monitors-on-and-off)
6. [Choosing Menu Bar Widgets](#6-choosing-menu-bar-widgets)
7. [The Monitor Modules in Detail](#7-the-monitor-modules-in-detail)
8. [Reading the Pop-up Panels](#8-reading-the-pop-up-panels)
9. [The Text Widget and Its Variables](#9-the-text-widget-and-its-variables)
10. [Combined (Merged) Modules](#10-combined-merged-modules)
11. [Application Settings](#11-application-settings)
12. [macOS Desktop & Notification-Center Widgets](#12-macos-desktop--notification-center-widgets)
13. [System Stats (Remote Monitoring)](#13-system-stats-remote-monitoring)
14. [Fan Control & Sensors](#14-fan-control--sensors)
15. [Backing Up & Restoring Your Settings](#15-backing-up--restoring-your-settings)
16. [Launch Options](#16-launch-options)
17. [Troubleshooting](#17-troubleshooting)
18. [Frequently Asked Questions](#18-frequently-asked-questions)
19. [Reference](#19-reference)

---

## 1. Quick Start

```text
1. Download Stats.dmg (or run `brew install stats`).
2. Open the DMG and drag Stats into Applications.
3. Launch Stats from Applications.
4. The Settings window opens automatically on first launch.
5. Pick the monitors you want (CPU, RAM, etc.) and choose a widget for each.
6. Watch your stats appear in the menu bar. Click any icon for details.
```

When you launch Stats for the first time, a short setup screen appears, and then — because no widgets are active yet — the **Settings** window opens automatically so you can choose what to monitor.

> [!TIP]
> Start small. Enable **CPU** and **Memory** first with the **Mini** widget, get comfortable clicking the icons to open their pop-ups, then add GPU, Disk, Network, and the rest as you need them. Each active monitor uses a little CPU and energy, so only run what you actually watch.

---

## 2. Requirements

| Requirement | Detail |
|---|---|
| Operating system | macOS 12 (Monterey) or newer |
| Architecture | Apple Silicon and Intel Macs |
| Cost | Free |
| License | MIT |

> [!NOTE]
> If you are on an older macOS release that the current version no longer supports, a **legacy build** is available at [mac-stats.com/downloads](https://mac-stats.com/downloads).

Some features have additional, automatic requirements that Stats checks for you:

- **Battery monitor** appears only on Macs that report a power source (i.e. notebooks).
- **Fan control** requires installing a small privileged helper (see [Fan Control & Sensors](#14-fan-control--sensors)). It is in legacy maintenance mode.
- **macOS desktop widgets** require turning on a setting because they are disabled by default (see [section 12](#12-macos-desktop--notification-center-widgets)).

---

## 3. Installation

Stats can be installed manually from a disk image or through Homebrew. Both deliver the same app.

=== "Manual (DMG)"

    1. Download the latest release: [Stats.dmg](https://github.com/exelban/stats/releases/latest/download/Stats.dmg).
    2. Open the downloaded `Stats.dmg`.
    3. Drag the **Stats** app into your **Applications** folder.
    4. Eject the disk image and launch Stats from Applications.

=== "Homebrew"

    Open the **Terminal** app and run:

    ```bash
    brew install stats
    ```

    Expected result:

    ```text
    ==> Installing Cask stats
    🍺  stats was successfully installed!
    ```

    Launch Stats from Applications (or with `open -a Stats`).

> [!IMPORTANT]
> Stats updates itself. When a new version is available it can download and install the update for you (controlled by the **Check for updates** setting). If you installed through Homebrew you can also update with `brew upgrade stats`, but the built-in updater works regardless of how you installed.

### First launch

On the very first launch you may see a brief setup window. After it finishes, Stats opens **Settings** automatically because nothing is being monitored yet. Choose your monitors there (next sections).

> [!NOTE]
> macOS may warn that Stats was downloaded from the internet. This is normal for any app distributed outside the App Store — open it once via the Applications folder to confirm.

---

## 4. Core Concepts

Stats is built around a few simple ideas. Understanding them makes everything else obvious.

**Module**
: A single monitor — **CPU**, **GPU**, **RAM** (memory), **Disk**, **Sensors**, **Network**, **Battery**, **Bluetooth**, **Clock**, or **Remote**. Each module can be turned on or off independently.

**Widget**
: The compact visual that a module draws in the menu bar — for example a percentage number, a line chart, or a battery icon. A module can offer several widget styles, and you choose which ones to show.

**Pop-up**
: The detailed panel that appears when you click a module's menu bar widget. It shows the full breakdown (per-core load, top processes, network addresses, battery health, and so on).

**Settings**
: Per-module options (colors, update frequency, which disk or GPU to track, etc.) plus global application settings. Reached from the Settings window or the gear icon inside any pop-up.

The relationship is: **a module reads data → draws one or more widgets in the menu bar → opens a pop-up with details when clicked.**

> [!TIP]
> A module only appears in the menu bar if it is **enabled *and* has at least one active widget**. If you enable a module but see nothing, you probably haven't picked a widget for it yet.

---

## 5. Turning Monitors On and Off

### Opening Settings

There are several ways to open the Settings window:

- Click any Stats menu bar icon to open its pop-up, then click the **⌘ (command)** button in the pop-up header.
- If Stats is paused or showing its app icon, click the icon.
- Re-open the app from Applications (Stats brings Settings to the front).

The Settings window has a **sidebar** listing the **Dashboard** plus every available module, and a main area showing the selected item's options.

### Enabling a module

1. Open **Settings**.
2. Select a module in the sidebar (e.g. **CPU**).
3. Use the **toggle in the window toolbar** to switch the module on or off.

When you enable a module, Stats immediately starts reading its data and shows its widget(s) in the menu bar. When you disable it, its menu bar items disappear and it stops reading data (saving energy).

> [!NOTE]
> Stats remembers each module's on/off state across restarts. Modules that aren't supported on your Mac (for example Battery on a desktop, or Fan readings without the helper) are hidden or stay off automatically.

### The Dashboard

The **Dashboard** entry at the top of the sidebar is read-only system information about your Mac:

| Field | What it shows |
|---|---|
| Device | Model name, model identifier, and macOS version (with build number) |
| Processor | CPU name, physical/logical core counts, and efficiency/performance/super core counts on Apple Silicon |
| Memory | Installed RAM modules with size, speed, type, and slot/channel |
| Graphics | GPU name(s) with core count and VRAM |
| Disks | Internal/connected drives with capacity |
| Display | Connected displays with size, resolution, and refresh rate |
| Model identifier / Production year / Serial number | Hardware identity |
| Uptime | Time since last boot |

---

## 6. Choosing Menu Bar Widgets

Each module's settings page lets you pick which **widget(s)** appear in the menu bar. You can enable more than one widget per module (for example a number *and* a line chart).

Stats offers the following widget styles (each module supports the subset that makes sense for its data — see [section 7](#7-the-monitor-modules-in-detail)):

| Widget | Looks like | Best for |
|---|---|---|
| **Mini** | A label + a single percentage/value | Compact, at-a-glance load |
| **Line chart** | A small scrolling line graph | Seeing the recent trend |
| **Bar chart** | Vertical bars (one per core/disk/etc.) | Per-core or split breakdowns |
| **Pie chart** | A filled circle | Proportional usage |
| **Network chart** | Up/down area chart | Upload vs. download over time |
| **Speed** | Up/down arrows with values | Live transfer/IO rates |
| **Battery** | A battery glyph that fills/charges | Battery level + charging state |
| **Battery details** | Battery glyph + percentage/time | Battery with extra text |
| **Memory** | Free/used text pair | RAM and disk capacity |
| **Stack (sensors)** | A vertical stack of label/value rows | Multiple sensors, devices, or clocks |
| **Label** | A small text label | Naming a sensor reading |
| **Tachometer** | A radial gauge | Gauge-style load display |
| **State** | A colored dot | Up/down or pressure status |
| **Text** | Custom text from a template | Fully custom readouts |

> [!TIP]
> To reorder the icons of *different* apps in the menu bar (including Stats' own icons), hold **⌘ (command)**, drag the icon to where you want it, and release ⌘. macOS — not Stats — controls this ordering, so it may shuffle once after the first reboot following installation.

Most widgets expose their own small settings (colors, value to display, whether to show a frame, etc.) directly under the widget picker on the module's settings page.

---

## 7. The Monitor Modules in Detail

This section covers each module, the data it shows, the widgets it supports, and its notable options. All values, colors, and behaviors here come directly from how the module is built.

### 7.1 CPU

Monitors processor load.

**Widgets:** Mini, Line chart, Bar chart, Pie chart, Tachometer.

**Key options:**

- **Show usage per core** — the bar chart draws one bar per logical core instead of a single total bar.
- **Split the value (system / user)** — splits load into **system** and **user** portions, each with its own color (defaults: system = red, user = blue).
- **Group by clusters** — on Apple Silicon, groups load into **efficiency**, **performance**, and **super** core clusters, each with its own color (defaults: e‑cores = teal, p‑cores = indigo, s‑cores = orange).
- **Colors** — system, user, efficiency, performance, and super core colors are all customizable (including a custom color picker).

**Pop-up shows:** total usage, per-core breakdown, system/user/idle split, average load (1/5/15 min), temperature, frequency (Apple Silicon) or scheduler limits (Intel), and the top processes by CPU.

> [!NOTE]
> CPU **temperature** sensors are thermal zones, not per-core readings. A label like "CPU Efficiency Core 1" is one temperature sensor inside the efficiency cluster, not the temperature of a single core.

### 7.2 GPU

Monitors graphics processor utilization.

**Widgets:** Mini, Line chart, Bar chart, Tachometer.

**Key options:**

- **Show GPU type** — prefixes the Mini widget value with the GPU type (`iGPU` integrated, `eGPU` external, `dGPU` discrete).
- **GPU selection** — if your Mac has more than one GPU, choose which one the widget tracks.
- **Update interval** — how often utilization is read.

**Pop-up shows:** utilization, render/tiler/ANE utilization where available, temperature, core/memory clock, fan speed, and FPS where the hardware exposes it.

### 7.3 RAM (Memory)

Monitors memory usage and pressure.

**Widgets:** Mini, Line chart, Bar chart, Pie chart, Memory, Tachometer, State (dot), Text.

**Key options:**

- **Split the value** — bar/pie/tachometer/memory widgets split memory into **app**, **wired**, and **compressed** segments (default colors: app = blue, wired = orange, compressed = pink).
- **Memory pressure** — Mini, Line chart, Bar chart, and Memory widgets reflect macOS memory pressure; the **State** dot is colored by pressure level.
- **Text widget value** — a custom template (default `$mem.used/$mem.total ($pressure.value)`); see [section 9](#9-the-text-widget-and-its-variables).

**Pop-up shows:** total/used/free, app/wired/compressed, cached, swap (used/total/free), swap‑ins/outs, memory pressure, and the top processes by memory.

### 7.4 Disk

Monitors drive capacity and read/write activity.

**Widgets:** Mini, Bar chart, Memory, Pie chart, Speed, Network chart, Text.

**Key options:**

- **Disk selection** — choose which drive the widget tracks (defaults to the root/boot volume).
- **Main color** — color used by the pie chart (default blue).
- **Text widget value** — default `$capacity.free/$capacity.total`; see [section 9](#9-the-text-widget-and-its-variables).

**Pop-up shows:** each drive's capacity (total/used/free), read/write activity, file system and connection type, and SMART data (drive health %, temperature, total read/written, power cycles, power-on hours) where available.

> [!NOTE]
> When you use the **Speed** or **Network chart** widget to show disk I/O, Stats automatically reads activity once per second so the chart stays smooth.

### 7.5 Network

Monitors upload/download bandwidth and connection details.

**Widgets:** Speed, Network chart, Text, State (dot for connectivity).

**Key options:**

- **Public IP refresh interval** — how often the public IP address is refreshed: **never** (default), **hourly**, every **12 hours**, or every **24 hours**.
- **Reset total usage** — optionally reset the cumulative upload/download totals **at app start**.
- **Widget activation threshold** — only "light up" the widget when transfer exceeds a threshold you set (with a size unit such as KB/MB/GB), keeping the menu bar quiet during idle periods.
- **Connectivity (ICMP) host** — Stats can ping a host to report up/down status and latency; you can change or disable the host.
- **Text widget value** — default `$addr.public - $status`; rich set of variables in [section 9](#9-the-text-widget-and-its-variables).

**Pop-up shows:** local and public IPv4/IPv6 addresses, DNS servers, interface name and type (Wi‑Fi/Ethernet/Bluetooth/other), Wi‑Fi details (SSID, BSSID, RSSI, noise, standard, channel, security), current and total bandwidth, and the top processes by network use.

> [!NOTE]
> To show your **public IP**, Stats asks `api.mac-stats.com` for it. See [External services](#external-services) for details and how to disable this.

### 7.6 Battery

Monitors battery level, charging, and health. Available only on Macs with a battery.

**Widgets:** Mini, Bar chart, Battery, Battery details.

**Pop-up shows:** charge level, charging/AC status, optimized-charging status, time to full/empty, cycle count, health (%), capacities (design/max/current), amperage, voltage, temperature, and adapter details (power, voltage, charging current/voltage).

> [!TIP]
> You can set **low/high battery notifications** in the Battery module's settings so Stats alerts you when the level crosses a threshold.

### 7.7 Sensors

Monitors temperature, voltage, power, and fan sensors via the SMC.

**Widgets:** Mini (single selected sensor), Stack (multiple sensors), Bar chart (fans).

**Key options:**

- **Sensor selection** — choose which sensors are shown and, for the Mini widget, which single sensor is displayed (default `Average System Total`).
- **Fan value** — show fan speed as a **percentage** (default) or as **RPM**.
- **Show unknown / HID sensors** — reveal additional discovered sensors.

> [!CAUTION]
> The **Sensors** and **Bluetooth** modules are the most resource-intensive. If you want to reduce Stats' energy/CPU footprint, disabling these two can cut its usage by up to ~50% in some cases.

### 7.8 Bluetooth

Shows battery levels of paired/connected Bluetooth devices (AirPods, mice, keyboards, controllers, etc.).

**Widgets:** Stack (one row per device/battery reading).

**Key options:** per-device visibility and optional low-battery notification thresholds.

### 7.9 Clock

Shows one or more clocks, including multiple time zones and calendars.

**Widgets:** Stack.

**Key options:**

- **Add multiple clocks**, each with its own **name**, **time-zone**, **calendar**, and **date format** string (e.g. `yyyy-MM-dd HH:mm:ss`).
- Time zones include **Local** plus fixed UTC offsets (UTC‑12:00 through UTC+14:00, including half/quarter-hour offsets) and all named IANA zones.
- Calendars include Gregorian (default), Buddhist, Chinese, Coptic, Ethiopic, Hebrew, ISO‑8601, Indian, Islamic (and variants), Japanese, Persian, and ROC; macOS 26 adds several more (Bangla, Tamil, Vietnamese, and others).

> [!TIP]
> The Clock pop-up header has a **calendar** button that opens the macOS Calendar app.

### 7.10 Remote

Connects Stats to **System Stats**, an online dashboard that aggregates monitoring from multiple machines and external hosts. See [section 13](#13-system-stats-remote-monitoring).

**Widgets:** State (a single dot summarizing whether your remote machines/hosts are all up, all down, or mixed).

**Pop-up shows:** your remote machines and monitored hosts with online/up/down status, grouped as configured in your System Stats account.

---

## 8. Reading the Pop-up Panels

Click any module's menu bar widget to open its **pop-up**. The pop-up has a header with three controls:

| Control | Action |
|---|---|
| Left button | Opens **Activity Monitor** (jumps to the matching tab — CPU, Memory, Disk, Network, or Battery). For **Clock** it opens **Calendar**; for **Remote** it opens the System Stats site. |
| Title | The module name |
| **⌘** button | Opens this module's **Settings** |

Pop-ups resize to fit their content and scroll if they're taller than your screen. Click elsewhere (or press the close button that appears when you drag the pop-up) to dismiss it.

> [!TIP]
> You can assign a **keyboard shortcut** to open a module's pop-up. Set it in the module's pop-up settings; pressing the shortcut anywhere toggles that pop-up open/closed.

---

## 9. The Text Widget and Its Variables

The **Text** widget (available for RAM, Disk, and Network) renders a string you define, substituting live values for `$variables`. Variables use the form `$group.field` (or just `$group` for single-value ones).

### Memory (RAM) variables

| Variable | Meaning |
|---|---|
| `$mem.total` / `$mem.used` / `$mem.free` | Total / used / free memory |
| `$mem.active` / `$mem.inactive` / `$mem.wired` / `$mem.compressed` | Memory categories |
| `$mem.app` / `$mem.cache` | App memory / cached files |
| `$mem.swapins` / `$mem.swapouts` | Swap-in / swap-out counts |
| `$swap.total` / `$swap.used` / `$swap.free` | Swap usage |
| `$pressure.level` / `$pressure.value` | Memory pressure (numeric / textual) |

*Default:* `$mem.used/$mem.total ($pressure.value)`

### Disk variables

| Variable | Meaning |
|---|---|
| `$capacity.total` / `$capacity.used` / `$capacity.free` | Drive capacity |
| `$percentage.used` / `$percentage.free` | Used / free as a percentage |

*Default:* `$capacity.free/$capacity.total`

### Network variables

| Variable | Meaning |
|---|---|
| `$addr.public` / `$addr.publicV4` / `$addr.publicV6` | Public IP (any / v4 / v6) |
| `$addr.private` / `$addr.privateV4` / `$addr.privateV6` | Local IP (any / v4 / v6) |
| `$addr.countryCode` / `$addr.flag` | Country code / flag emoji of the public IP |
| `$interface.displayName` / `$interface.BSDName` / `$interface.address` / `$interface.transmitRate` | Active interface details |
| `$wifi.ssid` / `$wifi.bssid` / `$wifi.RSSI` / `$wifi.noise` | Wi‑Fi identity & signal |
| `$wifi.standard` / `$wifi.mode` / `$wifi.security` | Wi‑Fi protocol details |
| `$wifi.channel` / `$wifi.channelBand` / `$wifi.channelWidth` / `$wifi.channelNumber` | Wi‑Fi channel details |
| `$status` | Connection status (UP/DOWN) |
| `$upload` / `$upload.total` | Current / cumulative upload |
| `$download` / `$download.total` | Current / cumulative download |
| `$type` | Connection type (wifi/ethernet/bluetooth/other) |
| `$icmp.status` / `$icmp.latency` | Connectivity host up/down / latency |

*Default:* `$addr.public - $status`

**Example (Network):**

```text
$wifi.ssid · $download/$upload · $status
```

renders as something like:

```text
HomeWiFi · 1.2 MB/s/240 KB/s · UP
```

---

## 10. Combined (Merged) Modules

By default each module occupies its own menu bar slot. **Combined modules** merges all enabled modules into a **single** menu bar item, which saves space.

Enable it in **Settings → application settings → Combined modules**:

| Option | Effect |
|---|---|
| **Combined modules** | Master on/off switch for merging |
| *(module strip)* | Drag the module icons to set their left-to-right order |
| **Spacing** | Gap between modules in the merged item |
| **Separator** | Draw a thin divider line between modules |
| **Combined details** | When on, clicking the merged item opens a single pop-up with every module's summary; when off, each module's widget opens its own pop-up |

> [!NOTE]
> Reordering modules here also sets the order they appear in the combined item and in the combined pop-up.

---

## 11. Application Settings

Open **Settings** and select the application-settings area (the gear/options section, reachable from the Dashboard area). These options apply to Stats as a whole.

| Setting | Options / default | What it does |
|---|---|---|
| **Check for updates** | Silent (default), at launch, daily, weekly, monthly | How often Stats checks for and installs updates. **Silent** installs updates in the background. |
| **Temperature** | System (default), Celsius, Fahrenheit | Forces a temperature unit or follows the system setting. |
| **Show icon in dock** | Off (default) | Shows a Dock icon in addition to the menu bar. |
| **Start at login** | Off | Launches Stats automatically when you log in. |
| **Keep the menubar items position** | Off | Asks macOS to preserve the position of Stats' menu bar items. |
| **macOS widgets** | Off (default) | Enables data flow to macOS desktop/Notification-Center widgets (see [section 12](#12-macos-desktop--notification-center-widgets)). |
| **Combined modules** | Off | Merges modules into one menu bar item (see [section 10](#10-combined-merged-modules)). |
| **Settings: Export / Import / Reset** | — | Save, restore, or reset all preferences (see [section 15](#15-backing-up--restoring-your-settings)). |

There is also a **Stress tests** section (run an **Efficiency cores**, **Performance cores**, or **GPU** load test) that's useful for verifying temperature/fan behavior under load.

> [!IMPORTANT]
> Turning on **Show icon in dock** also makes Stats behave like a regular app (it appears in the Dock and ⌘-Tab switcher). Turn it off to return to a pure menu bar utility.

---

## 12. macOS Desktop & Notification-Center Widgets

Stats can publish data to native macOS widgets (the ones you add to your desktop or Notification Center). These are **off by default**.

To enable them:

1. Open **Settings**.
2. Turn on **macOS widgets**.
3. Add a Stats widget the normal macOS way (right-click the desktop → **Edit Widgets**, or open Notification Center → **Edit Widgets**, and find **Stats**).

> [!WARNING]
> macOS widgets are disabled by default on purpose. The system process that feeds widgets (`chronod`) can generate heavy load, so Stats only sends data once you opt in with the **macOS widgets** switch. If your desktop widget shows no data, this setting is almost always the reason.

---

## 13. System Stats (Remote Monitoring)

**System Stats** is an optional online service ([app.system-stats.com](https://app.system-stats.com)) that collects monitoring from one or more Macs and external hosts into a single dashboard. The **Remote** module and the **System Stats** settings section connect Stats to it.

Configure it in **Settings → System Stats**:

| Field | Purpose |
|---|---|
| **Authorization / Login** | Sign in to your System Stats account |
| **Identificator** | This machine's unique ID |
| **Plan** | Your account plan (e.g. Free) |
| **Monitoring** | Send this machine's stats to the service |
| **Control** | Allow remote control actions (see warning) |
| **Logout** | Disconnect this machine |

> [!CAUTION]
> Enabling **Control** lets the remote service perform control actions on this machine. Stats shows a warning before enabling it — leave it off unless you specifically need remote control and understand the implications.

> [!NOTE]
> System Stats is a separate, optional cloud service. You can use every local monitor in Stats without ever logging in.

---

## 14. Fan Control & Sensors

Stats can read fan speeds (in the **Sensors** module) and, on supported Macs, control them. Fan **control** requires a small **privileged helper** to be installed, which macOS will prompt you to authorize with your administrator password.

> [!WARNING]
> **Fan control is in legacy maintenance mode.** It does not receive new features or fixes and is kept only because it still works acceptably on older Macs. Treat it as a best-effort feature.

To uninstall the fan helper later, open **Settings** and use **Uninstall fan helper** (this option only appears when the helper is installed).

> [!CAUTION]
> Sensor labels such as "CPU Efficiency Core 1" identify a **thermal sensor in a cluster**, not an individual core's temperature. Apple changes sensor keys with each new chip, so some sensors on the newest hardware may be unlabeled or missing until support is added.

---

## 15. Backing Up & Restoring Your Settings

All of Stats' preferences can be exported to a file and restored later — handy when setting up a new Mac.

| Action | How | Result |
|---|---|---|
| **Export** | Settings → **Export settings** → **Save** | Writes a `Stats.plist` file you choose the location for |
| **Import** | Settings → **Import settings** → **Choose file** | Loads settings from a previously exported `.plist` |
| **Reset** | Settings → **Reset settings** → **Reset** | Restores all defaults (Stats confirms, then restarts) |

> [!TIP]
> Export your `Stats.plist` after you've tuned everything the way you like. Importing it on another Mac reproduces your exact layout, colors, and module choices.

---

## 16. Launch Options

Stats accepts a few command-line arguments, useful for scripting or troubleshooting. Launch it from Terminal like this:

```bash
/Applications/Stats.app/Contents/MacOS/Stats --reset
```

| Argument | Effect |
|---|---|
| `--reset` | Resets all stored settings on launch |
| `--disable <names>` | Disables the listed modules (comma-separated, e.g. `--disable sensors,bluetooth`) |
| `--mount-path <path>` | Internal: unmounts/cleans a temporary DMG mount after an update (path must be inside a temp directory) |
| `--dmg-path <path>` | Internal: deletes a downloaded `.dmg` after an update (must be in Downloads and end in `.dmg`) |

> [!NOTE]
> `--mount-path` and `--dmg-path` are used by the auto-updater to clean up after installing a new version; you normally never pass them yourself.

---

## 17. Troubleshooting

Each entry uses the format **Symptom → Cause → Solution**.

### Stats icons do not appear in the menu bar

**Cause:** macOS 26 introduced a privacy control that requires apps to be explicitly allowed to show menu bar items, even when Stats is running with active widgets.

**Solution:** Open **System Settings → Menu Bar** and toggle **Stats** **ON**.

**Prevention:** After any major macOS upgrade, re-check this setting.

### Desktop / Notification-Center widget shows no data

**Cause:** Communication with macOS widgets is disabled by default (to avoid heavy `chronod` load).

**Solution:** Open **Settings** and turn **macOS widgets** **ON**, then re-add the widget.

### A module is enabled but nothing shows in the menu bar

**Cause:** The module has no active widget, or **Combined modules** is hiding it.

**Solution:** Open the module's settings and enable at least one widget. If using Combined modules, confirm the module is enabled and present in the module strip.

### Network shows "DOWN" even though the internet works

**Cause:** Intermittent interface status detection; reported in community issues (e.g. [#2545](https://github.com/exelban/stats/issues/2545), [#3293](https://github.com/exelban/stats/issues/3293)).

**Solution:** Quitting and re-launching Stats reliably clears the false "DOWN" state. Make sure you're on the latest version, where detection has been improved.

### Public IP is blank in the Network pop-up

**Cause:** The public-IP lookup uses `api.mac-stats.com`; if you block it with a network filter (e.g. Little Snitch), the public IP can't be retrieved.

**Solution:** Allow `api.mac-stats.com`, or accept that the public IP and update checks won't work while it's blocked.

### "Install Fan Helper does not work" / fan helper won't install

**Cause:** The privileged helper installation can fail in some environments (reported in [#3330](https://github.com/exelban/stats/issues/3330), [#3331](https://github.com/exelban/stats/issues/3331), [#3332](https://github.com/exelban/stats/issues/3332)).

**Solution:** Approve the administrator-password prompt when it appears. If a previous helper is in a bad state, use **Settings → Uninstall fan helper**, then try installing again. Remember fan control is legacy and unsupported.

### High CPU usage from Stats

**Cause:** Reading some metrics is inherently expensive; **Sensors** and **Bluetooth** are the heaviest. On some chips a specific module can spike a core (e.g. [#3294](https://github.com/exelban/stats/issues/3294)).

**Solution:** Disable Sensors and/or Bluetooth, or increase the **update interval** for heavy modules. Make sure you're on the latest version.

### After an update, Stats won't open / fails Gatekeeper

**Cause:** In rare cases an update could corrupt framework symlinks ([#3218](https://github.com/exelban/stats/issues/3218)).

**Solution:** Delete Stats from Applications and reinstall the latest [Stats.dmg](https://github.com/exelban/stats/releases/latest/download/Stats.dmg).

### The app crashed

**Cause:** Various.

**Solution:** First confirm you're on the latest version — a fix may already be released. If still crashing, search [existing issues](https://github.com/exelban/stats/issues) before opening a new one.

---

## 18. Frequently Asked Questions

**Q: Is Stats free?**
Yes. Stats is completely free and open source under the MIT license.

**Q: How do I change the order of the menu bar icons?**
Hold **⌘ (command)**, drag the icon to the position you want, and release ⌘. macOS controls icon order, so it may change once after the first reboot following installation.

**Q: How do I reduce Stats' energy impact or CPU usage?**
Disable modules you don't need — especially **Sensors** and **Bluetooth**, the two most expensive. You can also lengthen each module's update interval.

**Q: Why does the Sensors module show the "wrong" number of CPU/GPU cores?**
Those are thermal **sensors** (thermal zones), not cores. Each cluster contains several sensors that don't map one-to-one to cores.

**Q: What external servers does Stats contact, and can I block them?**
`api.mac-stats.com` (update checks + public IP), `api.github.com` (fallback update check), and — only if you use Remote — `app.system-stats.com`. You can block the first two with a network filter; you'll just lose update checks and public-IP display.

**Q: Does Stats support Windows or Linux?**
No. Stats is a macOS application.

**Q: How do I monitor a specific disk or GPU instead of the default?**
In the Disk or GPU module settings, choose the drive/GPU you want from the selector.

**Q: Can I get a notification when my battery is low or memory pressure is high?**
Yes — several modules (Battery, RAM, CPU, GPU, Disk, Sensors, Network, Bluetooth) support notifications you can configure in their settings.

**Q: How do I show multiple time zones?**
In the **Clock** module, add a clock for each zone, each with its own name, time zone, calendar, and format.

**Q: My menu bar is crowded. Can Stats use just one icon?**
Yes — turn on **Combined modules** to merge everything into a single menu bar item.

**Q: Can I move my Stats setup to a new Mac?**
Yes — **Export settings** to a `Stats.plist` on the old Mac and **Import settings** on the new one.

**Q: Why was my GitHub issue closed without a response?**
Most likely it duplicates an existing issue that already has an answer. Search closed issues for your topic.

**Q: How can I contribute or request a feature?**
Open an issue first to discuss it. Pull requests are expected to map to a discussed issue (language/translation changes are an exception).

**Q: What languages does Stats support?**
Many — including English, German, French, Spanish, Italian, Portuguese, Russian, Ukrainian, Polish, Czech, Dutch, Turkish, Korean, Japanese, Simplified and Traditional Chinese, and more than two dozen others contributed by the community.

---

## 19. Reference

### Modules at a glance

| Module | Monitors | Widgets |
|---|---|---|
| CPU | Processor load, temperature, frequency, processes | Mini, Line, Bar, Pie, Tachometer |
| GPU | Graphics utilization, temperature, clocks | Mini, Line, Bar, Tachometer |
| RAM | Memory usage, pressure, swap, processes | Mini, Line, Bar, Pie, Memory, Tachometer, State, Text |
| Disk | Capacity, read/write, SMART | Mini, Bar, Memory, Pie, Speed, Network chart, Text |
| Network | Bandwidth, IP, Wi‑Fi, connectivity, processes | Speed, Network chart, Text, State |
| Sensors | Temperature/voltage/power/fans | Mini, Stack, Bar (fans) |
| Battery | Level, charging, health, adapter | Mini, Bar, Battery, Battery details |
| Bluetooth | Device battery levels | Stack |
| Clock | Multiple time zones/calendars | Stack |
| Remote | System Stats machines/hosts | State |

### Default values

| Setting | Default |
|---|---|
| Check for updates | Silent |
| Temperature units | System |
| Show icon in dock | Off |
| macOS widgets | Off |
| Combined modules | Off |
| Network public-IP refresh | Never |
| Sensors fan value | Percentage |
| Sensors default Mini sensor | Average System Total |
| Module update interval | 1 second |

### External services

| Host | Used for |
|---|---|
| `api.mac-stats.com` | Update checks + public IP lookup |
| `api.github.com` | Fallback update check |
| `app.system-stats.com` | Remote / System Stats dashboard (only if you log in) |

### Useful links

- Releases & downloads: <https://github.com/exelban/stats/releases>
- Legacy builds: <https://mac-stats.com/downloads>
- Issue tracker: <https://github.com/exelban/stats/issues>
- License (MIT): <https://github.com/exelban/stats/blob/master/LICENSE>

---

_Generated June 2026 from exelban/stats at 89ac79e. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._