Headroom

I built Headroom for my own machine: a 16 GB MacBook Pro that runs local language models. On that Mac, memory runs out as often as disk does, and macOS explains neither. Storage settings show “System Data” as one grey bar, and when a model does not fit in memory the whole machine stalls with no warning.

Headroom takes both apart. It is a SwiftUI app for Apple silicon, with a command-line tool and a small privileged helper alongside it.

What it does

• System Data, explained. A scan sorts what it finds into caches, developer tools, virtual machines, AI models, logs and so on. Each finding says what it is, who made it, and whether it is safe to remove.
• Duplicates without broken paths. Files are matched by size, then by their first and last 64 KB, then by a full SHA-256. In your own folders the extra copy goes to the Trash. Everywhere else it becomes an APFS clone, so both paths keep working and the data is stored once.
• Memory, with a plan. It says whether memory is costing speed right now, then lists the apps, dev servers and models that could give some back, each with its own button.
• Local AI.For Ollama, it estimates each model’s real footprint from its architecture, says whether it fits in the memory that is free, and can unload a model before the Mac locks up.
• Telemetry. A live dashboard of every core, memory, GPU, SSD, network, power, temperatures and fans, with five minutes of history. It only samples while you are looking at it.
• iPhone and iPad. Storage, battery health and the last 30 days of crashes for paired devices, read-only.
• Ask Headroom. Questions about this Mac, answered from what the app measures, by Apple Intelligence or Ollama on the device or by a cloud model with your own key.

How it stays safe

A cleanup app that deletes the wrong thing is worse than no app, so most of the design work went here.

• Nothing is deleted directly. Files go to the Trash, and a History screen can put a whole day or category back.
• Every finding has one of three levels: Safe, Review or Keep. Keep is explained but never offered for deletion.
• Checks run again right before anything is removed. Protected locations, folders a running program is working in, and git checkouts with uncommitted changes are all blocked.
• Tool cleanups such as brew cleanup or docker system prune show the exact command first and run only after you confirm.
• The administrator helper is a launchd daemon that does four fixed things and never takes a command. It only accepts connections from a copy of Headroom signed by the same team.
• A local model can give a second opinion on folders the knowledge base does not know, but its “yes” is capped at Review.

How it is built

The code is a Swift package with five targets: the app, a shared kit that holds the scanning and safety logic, the privileged helper and its protocol, and headroom-cli, which runs the same analysis as text. The safety-critical logic is covered by unit tests. The app updates itself: before installing a new version it checks the download against a published SHA-256 and confirms it is signed by the same developer as the running copy.