Headroom
Headroom in ChatGPT

Ask ChatGPT what’s filling your Mac, and what’s safe to clear.

The Headroom plugin knows more than 100 things that fill developers’ Macs, from node_modules and Xcode’s DerivedData to Docker’s disk image, local AI models and “System Data”. Share a scan and it shows your disk as an interactive sunburst, marks every cleanup candidate as safe, review or be careful, and writes a cleanup plan you run yourself.

Explain anything

“What is Docker.raw, and can I delete it?” You get what it is, which tool owns it, a safety label, the tool’s own cleanup command, and when to keep it. No scan needed.

Analyze a scan

Paste du output or attach a file. Headroom finds the big folders and the known cleanup candidates, and totals what’s reclaimable per safety label.

Plan a safe cleanup

Steps ordered safest first, with the owning tool’s command or the exact folders, and the space each frees. Nothing runs by itself: you choose what to copy into Terminal.

In ChatGPT you’ll also find Headroom in the sidebar (a searchable “What is this?” library and a scan explorer), as a Disk Explorer panel beside a conversation, and as the viewer for .headroom files in the desktop app.

Get a scan

ChatGPT can’t see your disk. A scan shows it.

Any of these works. None of them changes anything on your Mac; they only measure folder sizes. Start with the one you already have.

Terminal, on any Mac

  1. Open Terminal (in Applications › Utilities) and run:
du -k -d 5 ~ 2>/dev/null | sort -rn | head -300
  1. Copy the output and paste it into ChatGPT with a question like “What’s using my disk?”
  2. If macOS asks whether Terminal may access a folder such as Documents, you can say no; du skips it and the rest still works.

This lists your 300 biggest folders, five levels deep, in kilobytes. Plain du without -k counts in 512-byte blocks; tell ChatGPT if that’s what you ran.

Headroom for Mac

The most detailed option: Headroom scans the whole disk in seconds, checks every rule against every file, and exports about 5,000 folders and all cleanup findings in a small file.

  1. Scan your disk or a folder, then choose File › Export Scan for ChatGPT…
  2. Attach the .headroom file in ChatGPT.

Or from Terminal, with Headroom’s command-line tool installed:

headroom export ~ -o ~/Desktop/home.headroom

To replace personal folder and file names with neutral labels (well-known names like node_modules and DerivedData stay), tick the box in the save dialog or add --redact:

headroom export ~ --redact -o ~/Desktop/home.headroom

About the Headroom app

ncdu

If you use ncdu, export a folder as JSON and attach the file:

ncdu -o ~/Desktop/home-ncdu.json ~

ncdu’s JSON export (format 1) is supported; its newer binary export isn’t.

What’s in a scan

Folder and file names with their sizes, and for Headroom exports item counts, last-modified days, the disk’s capacity and free space. Never file contents. Home-folder paths are written as ~, so your account name isn’t included.

Try it

No scan handy? Use the example.

A made-up developer Mac with a nearly full 494 GB disk: node_modules, Xcode, simulators, Docker and AI models. Every name in it is invented.

Example files

In the Headroom sidebar in ChatGPT, “Open the example” loads the same disk.

Things to ask

  • “What’s taking up space on my Mac?” (with a scan attached or pasted)
  • “Is it safe to delete Docker.raw?”
  • “What is System Data and why is it 80 GB?”
  • “Make me a cleanup plan with only the safe items.”
  • “Which of my projects have the biggest node_modules?”
Privacy and safety

Read-only, by design.

Nothing is deleted

The plugin has no way to touch your Mac. Plans are text: you decide which commands to run, and “be careful” items never come with a delete command.

Scans aren’t kept

Headroom’s server reads the scan you share to answer that request and keeps nothing: no storage, no logs of what you send, no account. Privacy policy

Staging, for Headroom users

Plans include headroom:// links that put the items in the app’s Cleanup Tray. The app still asks you to confirm, and removes things by moving them to the Trash.

Limits

What the plugin can’t do.

  • It can’t scan your disk. It only knows what’s in the scan you share, at that scan’s level of detail.
  • Its knowledge is about macOS and the developer tools in Headroom’s catalog. For anything else it says it doesn’t know rather than guessing.
  • With du output it can’t see the files next to a folder, so some matches (a folder named target without its Cargo.toml) are marked “check first”. Headroom exports don’t have that problem.
  • Scans pasted as text can be up to 4 MB; attached files up to 25 MB.
  • The .headroom file viewer works in the ChatGPT desktop app.

Using Codex or another coding agent on your Mac? The plugin’s skill uses Headroom’s headroom command-line tool directly when it’s installed. Questions: Support.