StatBar User Guide

Version 1.0.0 · macOS 13 or later · statbar.remnantsecurity.com

StatBar puts your Mac's vitals in the menu bar: CPU, GPU, memory, disk, network, battery, temperature and fans, plus optional weather. Click it for the details, open the Monitors window to see what is using your Mac, and use Free Up Space to clear the caches that developer tools and AI coding agents leave behind. If you run AI coding tools or local models, see For AI developers.

This guide matches StatBar 1.0.0. It requires macOS 13 or later, on Apple silicon or Intel. Fan control works on Apple silicon only.

Install

1. Open the download and drag StatBar.app into your Applications folder.
2. Open it from Applications. StatBar has no Dock icon and no window: it appears as a small readout in the menu bar.
3. Click the readout to open the menu.

On first launch StatBar asks for nothing. No permission prompt appears, no window opens, and nothing is sent anywhere. Every optional feature (Launch at Login, the helper, Weather) asks only when you switch it on.

The release build is distributed outside the Mac App Store. The final release is intended to be signed with a Developer ID and notarized by Apple, so Gatekeeper opens it without a warning. If macOS does show a prompt on first open, confirm it only if the app came from your own purchase.

Launch at Login

Choose Launch at Login in the menu. A check mark means it is on. macOS may show a "Background Items Added" notice the first time; that is macOS announcing the login item you just asked for. If it fails, StatBar shows the error macOS returned. Choose the item again to turn it off.

Keep StatBar in Applications while you use Launch at Login. Running it from a Downloads folder or a disk image can make macOS treat it as a different copy.

Reading the menu bar

Each stat is a column: a label on top, the value underneath. The bar sits on a small dark rounded plate so it stays readable on any wallpaper, light or dark.

Turn stats on and off with the checkable rows in the menu (CPU, GPU, Memory, Disk, Network, Battery, Temperature, Fans, AI Tools Memory). Everything is on by default except AI Tools Memory. A stat that is off is hidden and not measured at all, so it costs nothing.

If a stat is not available on your Mac, for example a battery on a desktop, it is left out of the bar. In the menu its row reads "unavailable" or "none".

Readings refresh every 2 seconds by default. Choose 1, 2, 5 or 10 seconds in Settings › Update Interval. StatBar stops sampling while the system or the display sleeps and starts again when both are awake.

What the colors mean

Every reading is one of five steps: low (green), moderate (yellow), elevated (orange), high (red) and critical. Critical turns white text on a filled red chip, so the worst state never depends on telling two hues apart. Every color is also printed as a number beside it.

Each stat has its own scale, because 86% means different things for different parts of your Mac. A step begins at the value shown and ends where the next begins.

Some stats follow their own rules:

• Memory follows the pressure level macOS reports, not the percentage. Normal pressure is green, a warning is orange, and critical pressure is the critical chip. Memory never shows yellow or red.
• Battery is judged by what is left, so its scale runs downward. While charging it is always green.
• Load average only means something per core: 1.0 per core is a full machine. The menu shows the raw load average and a tooltip gives the per-core figure.
• Fans that have stopped (OFF) show as low. Apple silicon fans stop entirely at idle.
• Network speed has no "bad", so it does not use the five steps. Download climbs through greens to a bright glow at very high speeds; upload runs from orange to red.

Color themes

Choose Settings › Color Theme:

• Bands (green to red) is the default.
• Colorblind-friendly uses the Okabe-Ito palette: sky blue, blue, orange and vermillion. It never pairs red with green, and download is in the blue family while upload is orange.
• Monochrome removes hue entirely. Readings are plain text, and critical inverts to dark text on a light chip. The numbers and arrows carry the meaning.

The theme changes immediately, without restarting.

The menu

Click the bar to open the menu, from top to bottom:

1. This Mac: your Mac's marketing name, its artwork in this unit's color, chip, memory, startup disk, serial number and macOS version, like About This Mac.
2. Live readings: CPU (with user and system split), Load (1, 5 and 15 minute averages), GPU, Memory (used and total, with swap and how much is free for models), Disk (used and total, and a forecast row when it is filling), Net (current rates, and session totals underneath), Battery (state and time remaining, with health and power lines), Temp (CPU average, hottest CPU sensor, GPU), Thermal (how hard macOS is throttling), Fans (RPM per fan, and auto or manual) and Weather when it is on. GPU also shows the memory in use. Click CPU, Mem, Disk, Net, GPU or Bat to open that monitor.
3. Top Offenders.
4. Open Monitors..., Free Up Space... and Copy Status for AI Agent.
5. The stat toggles, then Fan Control, Settings, Launch at Login, Help, About StatBar, Check for Updates... and Quit StatBar.

Rows update only while the menu is open.

Top Offenders

A switch at the top of the section chooses CPU, Disk I/O, Energy or AI Tools. The first three list the three heaviest apps right now, with their icons. AI Tools lists the three AI and developer tools using the most memory, each with its RAM and CPU (see For AI developers). StatBar remembers your choice.

• Helper processes are rolled up into their app, so a browser and its twenty helpers are one line.
• CPU is shown as a percentage of one core, so it can exceed 100% for an app using several cores. Energy is shown in watts. Disk I/O is bytes per second read from and written to your drive: it is disk activity, not network upload or download, and not free space.
• In the first three views, apps below a small floor (under 1% CPU, 10 KB/s of disk, or 0.05 W) are not listed, so a quiet Mac can show fewer than three. AI Tools lists only tools that are running.
• Sampling happens only while the menu is open. Rates need two samples, so the list appears about a second after you open the menu.
• Processes owned by the system are hidden from ordinary apps. Turn on Settings › Include System Processes if you want WindowServer, kernel_task and other root daemons to be counted.

Why there is no per-app network. macOS exposes per-app network traffic only through a command-line subprocess (nettop) or a private framework. StatBar uses neither: it runs no subprocesses to take its readings (the one exception is a quick pmset when the menu opens, to read the energy mode) and uses no private interfaces. The Network monitor shows per-interface totals instead. The GPU monitor likewise shows the whole device, not per-app GPU use.

Monitors

Choose Open Monitors... (Command-M while the menu is open), or click a reading in the menu. The window has one tab each for CPU, Memory, Disk, Network, GPU, Battery and Ports. Detail sampling runs only while the window is visible and not paused. Closing, hiding or minimizing it, or sleeping the Mac, stops it.

The tabs

• CPU: a bar for every core, with efficiency and performance cores averaged separately on Apple silicon, above a process list. Columns: Process, PID, CPU %, Parent, User. 100% means one full core.
• Memory: a memory graph with pressure, above the same process list sorted by memory. Memory is physical footprint, including compressed memory. Columns: Process, PID, Memory, Parent, User.
• Disk: mounted volumes with Used, Available, Capacity and Used %. APFS volumes can share one container's free space, so do not add the capacities together.
• Network: interfaces with Download/s, Upload/s, Received, Sent and Link. Wi-Fi shows signal strength, link rate and channel; the network name is deliberately not shown (see Permissions). VPN, loopback and physical interfaces can count overlapping traffic, so do not add them.
• GPU: device utilization, renderer and tiler load, memory in use and core count.
• Battery: charge, status, time estimate, health, cycle count, power flow, and adapter wattage. Desktop Macs show "No battery reading available".
• Ports: the TCP ports your processes are listening on. See The Ports tab.

The first CPU or network reading after opening or resuming is a baseline and shows an em dash. Real values follow on the next sample.

Sorting, search, filter

• Click a column heading to sort by it, and click it again to reverse. Each tab remembers its sort.
• Search matches a name, an exact PID, or part of an executable's path. On Disk it matches a volume name or path.
• All Processes / Apps Only / AI & Dev Tools (CPU and Memory) limits the list to real applications, or to processes that belong to an AI or developer tool (see For AI developers). It is remembered.
• Hierarchy nests each process under the one that started it, so you can see everything one tool is responsible for. Searching keeps a match's parents visible. Turn it off for a flat list sorted across every process. It is off by default and remembered.
• Icons shows each app's own icon beside its name, the same one you see in the Dock and Finder, found from the app's bundle. Processes that are not apps (scripts, daemons) get a plain executable icon. Untick it for a text-only table. It applies to the process tabs and the Ports tab, is on by default, and is remembered.
• Pause freezes the list. Resume takes fresh baselines. The footer shows Live, Paused or Sleeping, how many items are shown, and the time of the last sample.

The Parent column

Parent is an ancestry chain, not one hop, so you can tell which tool started a process without chasing PIDs row to row:

python3.13 (17986) ← uv ← codex ← ChatGPT

Read it right to left: ChatGPT started codex, which started uv, which started python3.13. Only the immediate parent shows a PID.

• The chain stops at four links or at launchd, which is never shown because every chain ends there. Runs of the same name are folded into one.
• If a process outlived its parent, StatBar names the parent it saw: launchd (1) ← unsloth-studio (63029). A parent that has since exited is marked (exited).
• StatBar can only attribute processes it watched start. Anything already running before the first Monitors window was opened in this launch, or before the last reboot, shows whatever parent it has now. Nothing is guessed.
• Hover over a Process name to see its full executable path.

Quit, Force Quit, Stop

Select a row, then use the buttons under the table.

Safety rules:

• The buttons are enabled only for processes you own. Other users' and system processes are read only, and the detail line says so.
• StatBar will not act on itself or on launchd (PID 1).
• The confirmation dialogs have Cancel as the default button.
• The signal is sent by the process's kernel audit token, checked after you confirm. If the process exited and its PID was reused by something else, the action is refused rather than hitting the wrong process.
• macOS may still refuse to stop a protected process. StatBar shows the error.
• Nothing is ever stopped automatically.

The Ports tab

Ports answers "what is holding :3000?" It lists every TCP port one of your own processes is listening on, with these columns:

• Process: the name of the process.
• Port: the port number.
• PID: its process ID.
• Reachable from: This Mac only when it listens on the loopback address (127.0.0.1 or ::1), Network (all) when it listens on every interface, and Network when it is bound to one specific non-loopback address. "Network (all)" means other devices on your network may be able to connect, subject to your firewall; check anything you did not mean to expose.
• Started by: what started it, as a process name and PID, for example npm (20395).

Select a row and use Stop Process... or Force Stop... under the table, with the same confirmations and rules as in Quit, Force Quit, Stop. The search box matches the process name.

Safety notes:

• Ports are read with libproc, the same system calls the other monitors use. StatBar runs no lsof, no netstat and no other subprocess, and sends no traffic to the ports.
• Only your own processes are listed. macOS does not let an ordinary app see other users' or system processes' sockets, and this tab does not use the root helper. A port held by a system service or another user will not appear, and cannot be stopped from here.
• Only TCP listeners are shown. UDP sockets and connections that are not listening are not.
• StatBar never lists or stops itself or launchd. The stop is checked against the process's identity after you confirm, so a reused PID is refused rather than hitting the wrong process.
• Sampling runs only while the Ports tab is on screen and not paused.

For AI developers

Coding agents and local models are heavy tenants: they hold gigabytes of memory, spawn long chains of helper processes, fill the disk with downloads and builds, and push the Mac into thermal throttling. StatBar has a few features aimed at that. All of them read the same process list the Monitors window uses. Nothing is sent anywhere.

How tools are recognized

StatBar recognizes tools by process names, executable paths and ancestry. It has a fixed list: Claude Code, Codex, Gemini CLI, Aider, Cursor, Windsurf, VS Code, the Claude app, ChatGPT, Ollama, LM Studio, llama.cpp, Jupyter, Docker, and Xcode and Simulators. A process belongs to a tool if its own name or path says so. Failing that, it belongs to a tool if something that started it does, so work a tool kicked off is charged to it: python3.13 ← uv ← codex counts as Codex.

This is a heuristic, not a registry. A tool that is renamed, wrapped, or installed somewhere unusual can be missed, and an unrelated process that happens to be started by a tool is counted as that tool's. The ancestry part also depends on StatBar having watched the process start (see The Parent column). A tool not on the list is not recognized.

AI Tools in Top Offenders

Choose AI Tools in the Top Offenders switch. It lists the three tools using the most memory right now, each with a line such as 4.2 GB RAM · 38% CPU: memory and CPU (as a percentage of one core, so it can exceed 100%), totalled over everything charged to that tool. Hover a row for its process count. The memory is RAM in use, not disk space. Memory is physical footprint. Nothing is listed when none of the listed tools is running.

Stuck agents

If a process that belongs to Claude Code, Codex, Gemini CLI or Aider (its own, or one it started) looks like it got away from its agent, a warning line appears under Top Offenders while the menu is open: ⚠︎ Codex: python3.13 may be stuck — 99% CPU, averaging 95% for 50 min. Hover for up to six; click to open Monitors on the AI & Dev Tools filter.

Two things are flagged, and only among your own processes:

• Spinning. Using at least 80% of a core right now, having averaged at least 60% of a core over a lifetime of 15 minutes or more.
• Left behind. Its agent has exited, so launchd now owns it, and it is still using real CPU (5% or more) or 200 MB or more of memory. This relies on StatBar having watched it start since StatBar launched.

It cannot tell a stuck process from a long build or test run, which is why it says may be. Editors, Ollama, Docker and Xcode builds are busy by design and are not judged. Nothing is stopped for you; use Stop Process in Monitors, which asks first. The same list appears in the status snapshot.

Which Ollama model is loaded

When Ollama is running, a line under Top Offenders reads like Ollama: qwen3:14b · 9.3 GB · 100% GPU · unloads in 4 min. "Stays loaded" means it is pinned. A model that is less than 100% on the GPU is running partly on the CPU, which is much slower. StatBar gets this by asking Ollama's own API at 127.0.0.1:11434, the loopback address of this Mac, only while Ollama is running and the menu is open (or when you take a snapshot). It contacts nothing else and does not try a custom Ollama address.

In the Monitors window, the CPU and Memory tabs have an AI & Dev Tools option in the process filter. It shows only processes that belong to a recognized tool, using the same rules. Combine it with Hierarchy to see what each tool has running underneath it.

The AI column in the menu bar

You can add an AI column to the bar itself. It shows the total memory held by recognized AI and developer tools, colored by that memory's share of your RAM, and uses the same recognition rules as the AI Tools view. It is off by default.

To turn it on, choose AI Tools Memory in the menu, in the same list of checkable rows as CPU and GPU (a check mark means it is on). Choose it again to turn it off. While it is off, StatBar does not measure it at all. When none of the listed tools is running, it reads a zero amount of memory.

Memory headroom, thermal state and disk forecast

Three extra lines in the menu answer "can this Mac take another job right now?":

• Under Memory: swap 1.2 GB · 18 GB free for models. Swap is how much memory has spilled to disk; a model that spills into swap runs very slowly. "Free for models" is free memory plus reclaimable file cache, capped at the amount macOS allows the GPU to map for Metal. Treat it as roughly the largest model that fits right now, not a guarantee: other apps can take memory before you load one, and a model needs room for its working data as well as its weights. Hover over the row for the cap on your Mac.
• GPU: the GPU row shows memory in use beside the utilization, for example GPU 46.0% 11.4GB in use. On Apple silicon the GPU shares the Mac's memory, so this is memory a model or a render currently has mapped. The figure is left off where macOS does not report it.
• Thermal: nominal, fair, serious or critical, as reported by macOS, with "Low Power Mode" added when it is on. Serious and critical mean the Mac is slowing itself down, which long agent runs and local models can cause.
• Under Disk: filling +2.1 GB/h · full in ~9.0 h. This row appears only while the disk is filling, which means used space has grown by at least 200 MB per hour over at least ten minutes of history. It is a straight-line estimate from that window, so a download that finishes or a cache that is cleared changes it. It is not shown when the disk is steady or emptying, and not right after launch, because StatBar keeps no history between launches.

Copy Status for AI Agent

Choose Copy Status for AI Agent in the menu. After about three seconds StatBar puts a Markdown summary on the clipboard, ready to paste into a prompt. It covers:

• the Mac's marketing name, chip and macOS version;
• thermal state and Low Power Mode;
• CPU use, load averages and CPU temperature;
• memory used, pressure, swap, and the free-for-models figure;
• disk free space, and the battery;
• the top processes by CPU and by memory, each with what started it;
• the AI and developer tools running, with their totals.

It contains no serial number. It is built on this Mac, copied to the clipboard, and sent nowhere.

The command line: --snapshot

Agents and scripts can ask for the same summary themselves, without opening the menu:

/Applications/StatBar.app/Contents/MacOS/StatBar --snapshot
/Applications/StatBar.app/Contents/MacOS/StatBar --snapshot --json
/Applications/StatBar.app/Contents/MacOS/StatBar --snapshot --with-cleanup

• It prints Markdown by default, or JSON with --json, and exits. It takes about three seconds, because rates need two samples. It does not need a running StatBar and does not touch the menu bar.
• --with-cleanup adds the sizes of the caches Free Up Space knows about, largest first. It only measures. Nothing is deleted. Deleting is done from the Free Up Space window, with your confirmation, or from the command line with an explicit --yes (see Clean from a terminal, or every Mac at once).
• It reads only what the app already reads, includes no serial number, and makes no request beyond this Mac (if Ollama is running it is asked, over 127.0.0.1, which model is loaded).

A sentence in your agent's instructions, such as "run StatBar --snapshot before starting a large build or loading a local model", is enough to put it to use.

Free Up Space

AI coding tools and developer workflows quietly fill a disk with caches that regenerate themselves: package downloads, build products, model files, simulators and container leftovers. Free Up Space... finds them, shows how big each one is, and clears the ones you tick.

Open it from the menu. It scans when it opens, and Scan runs it again. Nothing is deleted without two clicks: tick items, choose Clean N Selected..., then confirm in a dialog that lists every item and size. The window also shows how much space is free on this Mac.

Sizes are allocated disk space. A very large folder is measured for a limited time, so its figure can be a lower bound.

Safe to clear

These sit under Safe to clear, rebuilt automatically. Tools download or rebuild what they need on next use. Items marked "pre-ticked" are selected for you after a scan; you can untick them. Items that are not present on your Mac are not listed.

Three more items run a tool instead of deleting folders. None is pre-ticked, and none runs a shell:

If Xcode is running, items that depend on it show Quit Xcode first and cannot be ticked.

Review yourself

These sit under Review yourself: large, personal, or slow to get back. StatBar shows their size and a Show button that opens the folder in Finder. StatBar never deletes anything here.

• All simulators (~/Library/Developer/CoreSimulator/Devices)
• Ollama models (~/.ollama/models)
• LM Studio models (~/.lmstudio/models)
• Tart virtual machines (~/.tart/vms; remove with tart delete)
• Lima virtual machines (~/.lima; remove with limactl delete)
• Colima VM (~/.colima; remove with colima delete)
• Xcode archives (~/Library/Developer/Xcode/Archives)
• Codex data (~/.codex) and Claude Code data (~/.claude): sessions and logs
• Trash: opens the Trash in Finder so you can empty it yourself. macOS keeps the Trash private from apps, so no size is shown.

What is deleted, and what never is

• Every location is a fixed path under your home folder, written into the app. No path is ever taken from a process, a file or the network.
• Only the contents of a folder are removed, one item at a time. The folder itself stays.
• A folder is acted on only if it is a real folder, not a link, and does not resolve through a link to somewhere else.
• Symlinks are removed as links and never followed. Items on a different disk volume are skipped.
• The ten-minute rule. Any item whose modified time is within the last ten minutes is skipped as "in use" and counted as "left alone". Run it again later to clear those.
• Deletion is permanent. It does not use the Trash.
• Never touched: Documents, Desktop, Downloads, Pictures, Movies, Music, Public and Applications, your .ssh, .gnupg, .aws, .config, .kube and .docker folders, and the Mail, Messages, Safari, Keychains, Containers, Group Containers, Application Support and Preferences folders in your Library.
• It reads nothing from macOS-protected locations, so it asks for no permission. It makes no network requests.
• Tools (simctl, docker) run from fixed locations with fixed arguments, a minimal environment and a time limit.

When it finishes, the status line reads, for example, "Freed 4.2 GB, 3 left alone". Hover over it to see which items were skipped or failed and why. The list then rescans.

Several Macs

Free Up Space cleans only the Mac it runs on. To clean another Mac, run StatBar there. One license works on unlimited Macs, so install it on each.

Settings

Open them from Settings in the menu.

• Update Interval: 1, 2, 5 or 10 seconds. The default is 2.
• Appearance: Forge Dark (the default) gives the monitor windows a compact dark look. Follow macOS uses the system appearance.
• Color Theme: Bands, Colorblind-friendly or Monochrome. See above.
• Weather: see below.
• Include System Processes: see below.
• Reset Session Totals: zeroes the network totals shown under the Net row.

Weather

Weather is optional and off by default. It is the only part of StatBar that uses the internet.

1. Choose Settings › Weather › Show Weather. A panel asks for a city.
2. Start typing. Suggestions appear as you type. Choose one, then Use This Location.

The menu then shows conditions for that place, and Show in Menu Bar adds a WX column. You can switch between Celsius and Fahrenheit, use Refresh Now, or turn it off again, after which StatBar stops making requests.

How it works: the city suggestions are provided by Apple's MapKit, so what you type in that box goes to Apple. StatBar stores only the chosen coordinates and name. It then asks a free, keyless weather service for conditions every 30 minutes: the US National Weather Service inside the United States, and MET Norway everywhere else. Those requests carry your chosen coordinates and an identifying User-Agent, and no account or ID.

Include System Processes

An ordinary app cannot read other users' processes. About a quarter of them, such as WindowServer and kernel_task, fail every unprivileged check. Switch on Include System Processes and Top Offenders and the monitors can see them.

It uses the same small helper as fan control, so macOS asks you to approve it once in System Settings › General › Login Items (under Allow in the Background). The menu line under the setting shows the state:

• "Helper active" means it is working.
• "Approve StatBar in System Settings › Login Items" means it is waiting for you.
• "Helper not installed" means toggle it off and on again.

The helper is strictly read-only here. It reports counters and never sends signals to, or attaches to, a process. System and other users' processes still cannot be stopped from the Monitors window. The helper accepts connections only from this exact build of StatBar and exits when idle.

Fan Control

Fan control works on Apple silicon only. On an Intel Mac the menu says so. Reading temperatures and fan speeds never needs the helper; only changing fan speed does.

Choose a mode from Fan Control:

• Automatic (macOS): macOS decides. This is the default.
• Constant 25%, Constant 50%, Constant 75% or Full Speed.
• Follow CPU Temperature: ramps from each fan's minimum at 55 degrees C to its maximum at 85 degrees C, using the hottest CPU sensor.

Speeds are always kept between each fan's own minimum and maximum, both in the app and in the helper.

A constant speed is not allowed to starve a hot Mac. If the hottest CPU sensor passes 80 degrees C, a Constant mode steps up toward full speed, reaching it at 92 degrees C, and settles back once the Mac cools. The chosen mode is remembered across launches, so this floor applies whenever StatBar is running with a manual mode on.

The first time you pick a manual mode, StatBar registers its helper and opens System Settings › General › Login Items so you can approve it. This happens only after your click, and at most once a minute. Until you approve, the status line in the Fan Control menu reads "Helper: approve in System Settings › Login Items". Other states are "Helper: ready" and "Helper: controlling fans".

Safety fallbacks. Fans return to automatic when:

• you quit StatBar, or it crashes;
• the Mac goes to sleep;
• the helper hears nothing from StatBar for 30 seconds. StatBar re-sends at least every 10 seconds while a manual mode is on.

If the temperature reading is missing in Follow mode, StatBar hands the fans back to macOS rather than guessing. Fans and the helper cannot be exercised without root and your approval, so they have not been tested on every Mac model. Try a manual mode while you are watching the Fans row.

Remove StatBar Helper (at the bottom of the Fan Control menu) sets the mode back to Automatic and unregisters the helper.

Power Mode

On Macs that have an energy mode, the menu shows a Power Mode switch with three choices: Low Power (cooler, quieter, and longer battery life), Automatic (macOS decides), and High Power (sustained speed under heavy load, on the Macs that offer it, such as some MacBook Pro and Mac Studio models). A Mac with no energy mode, such as many desktops, does not show the switch, and a choice the Mac does not support is greyed out.

macOS only lets an administrator change this, so the first time you pick a mode StatBar asks you to approve its helper in System Settings › General › Login Items, exactly as for fan control, and only after your click. The helper runs /usr/bin/pmset with a fixed command for the mode you chose, then reads the setting back to confirm it took. If it did not, the switch returns to what the Mac is really doing and says why.

It changes the same persistent setting as System Settings › Battery › Energy Mode, for the power source you are on right now (battery or adapter), as System Settings does, so the other profile is left alone. It stays until you change it again. Reading the current mode needs no approval and happens only when the menu opens. The mode also appears in the status snapshot.

Clean from a terminal, or every Mac at once

StatBar --clean does what the Free Up Space window does, without a window. It works over SSH, on a Mac mini with no screen, from a script, or from a coding agent. It never deletes anything unless you add --yes.

S=/Applications/StatBar.app/Contents/MacOS/StatBar
$S --clean --list                # what could be cleared on this Mac, with sizes (changes nothing)
$S --clean --safe                # DRY RUN of the items the window pre-ticks (changes nothing)
$S --clean uv npm                # DRY RUN of just those items (ids come from --list)
$S --clean --safe --yes          # actually clean the pre-ticked items
$S --clean uv npm --yes          # actually clean just those
$S --clean --safe --json         # the same, machine readable

It is the same engine as the window, so it keeps every safety rule: only a fixed table of cache folders can be named (anything else is refused, with exit status 3), review-only items such as models, VMs, archives and the Trash are refused even with --yes, only the contents of a folder are removed, anything changed in the last ten minutes is left alone, DerivedData is refused while Xcode is running, and Docker is pruned only for a local engine. Exit status is 0 when done, 2 for bad usage, 3 when an id was refused and 4 when something failed. Nothing is read from standard input.

Every Mac at once. scripts/fleet.sh runs it over SSH on each Mac you list, with the same rules on each:

bash scripts/fleet.sh local mbp mini -- --safe          # dry run on this Mac, "mbp" and "mini"
bash scripts/fleet.sh mbp mini -- --safe --yes          # then clean them, once you have read the dry run

A dry run across three real Macs looks like this (abridged: a few small items are left out; sizes are what each Mac reported; nothing was deleted):

=== macbook-neo ===
| Item                         | Size   | Result      |
| uv cache (uv)                | 9.3GB  | would-clean |
| npm cache (npm)              | 6.8GB  | would-clean |
| Homebrew downloads (brew)    | 4.3GB  | would-clean |
Would free about 20.4GB.

=== macbook-pro ===
| uv cache (uv)                | 20.8GB | would-clean |
Would free about 20.8GB.

=== mac-mini ===
| uv cache (uv)                | 25.5GB | would-clean |
| npm cache (npm)              | 9.8GB  | would-clean |
| Homebrew downloads (brew)    | 7.2GB  | would-clean |
| Xcode DerivedData (derived)  | 4.4GB  | would-clean |
| pip cache (pip)              | 1.7GB  | would-clean |
Would free about 48.8GB.

That is about 90 GB reclaimable across the three Macs, found and reviewed from one terminal. StatBar has to be installed on each Mac you list, and one license covers unlimited Macs. Passwordless SSH (keys) is recommended, because the script uses non-interactive SSH. Without --yes it only reports.

Permissions and privacy

StatBar is built around one rule: ask once, only when asked, never again.

• At launch, nothing. No permission prompt, no network request, no window.
• Launch at Login asks macOS to register a login item, when you choose it.
• The helper (fan control or Include System Processes) needs a one-time approval in Login Items, when you pick a manual fan mode or switch on Include System Processes.
• Weather uses the network, when you switch it on.
• A declined or pending approval is shown as status text in the menu. StatBar does not keep asking, and opens System Settings at most once a minute, and only from a click.

StatBar does not use, and never asks for: Accessibility, Location, Automation, Full Disk Access, Screen Recording, Contacts or notifications. The Wi-Fi network name is deliberately not shown, because macOS gates it behind Location.

Data. No telemetry, no analytics, no accounts, no tracking, no update checker. Check for Updates... only opens the Gumroad product page in your browser. The app keeps no history of your readings. Its settings are stored locally in your user preferences.

Not sandboxed, on purpose. StatBar is distributed directly rather than through the Mac App Store because the App Store sandbox does not allow the kernel interfaces it uses to read stats without subprocesses. That is why it is a direct download.

Troubleshooting

StatBar is not in my menu bar. On a crowded menu bar, macOS can hide the right-hand items behind the » arrow. Turn off one or two stats in the menu to make the readout narrower, or quit another menu bar app. On a Mac with a notch, items that do not fit are hidden.

A value shows an em dash, "unavailable" or "none". That reading is not available on this Mac (a desktop has no battery, some Macs have no fans), or it is the first sample after a pause and needs one more tick.

The first values look strange. CPU, network and process rates need two samples. Give it a tick.

The helper says "Helper: approve in System Settings › Login Items". Open System Settings › General › Login Items, and under Allow in the Background switch StatBar on. If you dismissed the prompt, choose the fan mode or the Include System Processes setting again.

"Helper not installed" or "Helper missing from the app bundle". Choose Remove StatBar Helper, then pick a fan mode (or toggle Include System Processes off and on) to register it again. "Missing from the app bundle" means the app was modified or damaged; download it again.

Launch at Login will not turn on, or the helper keeps asking after every update. macOS ties these approvals to the app's code identity. Keep StatBar in Applications, and use the official download. A copy you compile yourself with no signing certificate gets a new identity on every build, so macOS asks again each time.

Reset all settings. Quit StatBar, then in Terminal run defaults delete local.statbar.StatBar, and open it again. This clears your stat toggles, interval, theme, sort choices, Weather location and fan mode.

Something looks wrong. Choose Help › Report a Problem... to start an email with your StatBar and macOS versions filled in. The address is iantrimble@remnantsecurity.com.

Uninstall

1. If you used fan control or Include System Processes, choose Fan Control › Remove StatBar Helper. This returns the fans to Automatic and unregisters the helper.
2. If you turned on Launch at Login, choose Launch at Login again to turn it off.
3. Open System Settings › General › Login Items and confirm StatBar is not listed under Open at Login or switched on under Allow in the Background. Switch it off if it is.
4. Choose Quit StatBar.
5. Drag StatBar.app from Applications to the Trash.
6. Optional: remove your settings with defaults delete local.statbar.StatBar.

Free Up Space does not install anything and leaves nothing behind. The folders it cleans belong to the other tools.

FAQ

What do I get for $9.95? StatBar.app and a lifetime license that works on unlimited Macs, with updates and email support for life. It is a single payment: there is no subscription. The download also includes the complete Swift source (Sources/main.swift), the build scripts and the icon.

How do I get updates? Gumroad emails you when a new version is published. Check for Updates... opens the product page in your browser. The app never checks on its own.

Can I use it on more than one Mac? Yes. One license works on unlimited Macs. Install it on each; there is no activation and no limit to count. It does not cover redistributing or reselling it.

Is there a subscription, or do I pay for support? No. It is a single payment. Updates and email support (iantrimble@remnantsecurity.com) are for life, at no extra cost.

Is it on the Mac App Store? No. See "Not sandboxed, on purpose".

Does it use the internet? Only if you turn on Weather. Out of the box it makes no request off your Mac. The one local exception: when Ollama is running, StatBar asks it over 127.0.0.1 which model is loaded.

How much does it cost my Mac to run it? StatBar uses one timer, one small sampler per stat, and no polling subprocesses. Measured on 15 October 2026 on three Macs (a MacBook Neo, a MacBook Pro with an M4 Max and a Mac mini with an M4) over 20 seconds with the Monitors window closed, it used 16.6 to 17.1 MiB of memory, 0.02 to 0.04% of one core, and 0 to 0.6 wakeups per second. With the Monitors window open it holds about 50 MiB. A good part of that is macOS's own window and control machinery, which macOS does not fully give back when the window closes, so memory settles near 50 MiB after the first time you open it, until you restart StatBar. Results vary by Mac and load.

Why is my CPU percentage over 100%? In the CPU monitor and Top Offenders, 100% is one core, so an app using several cores can exceed it. The bar's CPU figure is the total across all cores, out of 100%.

Why do some processes show a lower memory number than Activity Monitor? StatBar shows physical footprint, including compressed memory. Activity Monitor can show a different column.

Why is a port missing from the Ports tab? Only TCP ports that your own processes are listening on are shown. A port held by a system service or another user, or a UDP port, does not appear, and StatBar cannot stop those.

Why can't I stop some processes? The buttons work only on processes you own, never on StatBar, launchd or system processes. macOS can still refuse a protected process.

Does Free Up Space delete my projects? No. It only clears fixed cache and leftover folders listed above, and never touches Documents, Desktop, Downloads or your project folders. Review items are only shown, never deleted.

It said something was "left alone". Why? It was changed in the last ten minutes, or was on another volume. Run it again later.

Does it work with the tools I use? Free Up Space knows the locations listed in this guide. Tools that keep caches elsewhere are not covered, and StatBar does not guess.

The AI column is not in my bar. It is off by default. Choose AI Tools Memory in the menu. It reads zero when no recognized tool is running.

I am colorblind. Will it work? Yes. Choose Colorblind-friendly or Monochrome in Settings › Color Theme. Critical also uses a filled chip and every color sits beside a number.

Can I add my own stat? The source is included. Each stat is one small sampler class, and the code is made to be read and changed, by you or by your AI coding agent.

Keyboard shortcuts

StatBar lives in the menu bar, so its shortcuts work while its menu is open.

The destructive confirmation dialogs in Monitors and Free Up Space have Cancel as the default, so pressing Return cancels them. Copy Status for AI Agent has no keyboard shortcut.

Getting help

• Help › StatBar Help opens a short quick start inside the app.
• Help › User Guide (online) opens this guide.
• Help › Report a Problem... starts an email to iantrimble@remnantsecurity.com with your versions filled in.