# Disk Census

> Disk Census is a native macOS app that scans a Mac's disk, shows what uses the space, and frees what is safe to free: caches, build output, old app data, duplicates, large forgotten files and AI agents' leftovers. Scanning is read-only; deleting is permanent and happens only when a person approves it or asks for it. Its engine also ships inside the app as the `census` command line, for scripts and AI agents.

This is the full description of Disk Census for AI agents and LLMs, in one file. Last updated 11 October 2026. The short index is at https://diskcensus.com/llms.txt.

## About Disk Census

- **What it is:** a storage utility for the Mac. It scans the whole startup drive, the home folder or any folder, explains where the space went, and frees what is safe to free. Its totals add up to the disk's used space.
- **Who it is for:** Mac developers first, whose disks fill with Xcode data, package caches, build output and Docker, and anyone whose Mac keeps running out of space. AI agents are a second kind of user: they drive the same engine through `census` on a person's behalf.
- **Who makes it:** Disk Census is made by Moiz (https://x.com/moz_281), in London.
- **How it is built:** a native SwiftUI app with a Rust engine. The app runs the engine as `census serve`, and the same engine is the `census` command in a terminal, so the app and agents always get the same answers.
- **Platform:** macOS 12 or later, on Apple silicon and Intel Macs. Distributed as a notarized Developer ID app, outside the App Store, because the App Store sandbox can't reach what a disk cleaner needs.

What it stands for:

- **Never surprise-delete.** Nothing is deleted until a person approves a visible list of exact items, and permanent deletion is stated plainly.
- **Know the developer's tools.** It separates what rebuilds itself from what costs time, bandwidth or data to restore, and says which is which.
- **Honest numbers.** Totals reconcile to the disk. What it can't read is shown, never hidden.
- **One engine, two doors.** The app and AI agents use the same engine and see the same results.

## Features

### Scanning

- Scan the whole startup drive, the home folder, or any folder (⌘O). Scan with ⌘R and stop with ⌘. at any time.
- Repeat scans read only what changed since the last one, using macOS's file change history, so they finish in a fraction of the first scan's time.
- Sizes are real space on disk. Hard links and APFS clones count once, folders macOS links into two places are walked once, and other drives aren't mixed in.
- Space no readable file accounts for (snapshots, the Recovery volume, files macOS protects, folders it couldn't read) is shown as **Hidden space**, so the rows always add up to the used space that Disk Utility reports.
- Without Full Disk Access, Disk Census still works with what it can read, and says what it skipped.

### Overview

- A capacity ring and the volume's used and free space.
- **Used Space** by category: macOS, Applications, App data, Documents, Developer, AI agents, Caches, Logs, Trash, Other users, System Data and Hidden space. Applications and App data open Apps, Developer opens DevTools, and AI agents opens AI Agents.
- **Safe to Clean:** how much of the caches, logs, build output and old versions can go, with one Clean button that asks before it deletes.
- **Largest:** the five largest files or folders, linking to Large Files.
- **Browse Folders:** drill into any folder as a bar of its largest items, with Quick Look and Reveal in Finder.
- **Empty Trash:** a Trash button with the Trash's live size.

### Large Files

- The biggest files or folders the person can delete, largest first.
- Filters: larger than 50 MB to 5 GB, last opened, and last modified (any time, or over 1 month to 2 years ago).
- Each row shows the item's size, when it was last opened (from Finder) and modified, and where it lives.
- Space opens Quick Look and Return reveals the item in Finder. Tick items and delete them after a confirmation that says they won't go to the Trash.
- It never lists macOS's own files, app bundles (Apps removes those), synced folders such as iCloud Drive and Dropbox, the Trash, or anything the person can't delete. Items in use by an app are skipped.

### Apps

- Every installed app with its version and total size, including its data. Search, sort, and show or hide Apple's apps.
- Select an app to see its data by location (caches, preferences, containers, support files), with how sure Disk Census is that each item belongs to it.
- Uninstall one app, or tick several and uninstall them together. A sheet lists every item: the app's own data is ticked, shared and loosely matched items are not, and the person decides.
- A running app is asked to quit; nothing is force-quit. Apple's apps are never offered for removal.

### DevTools

- Developer caches and build output, by tool: Xcode, Homebrew, npm, pnpm, Yarn, Bun, Cargo, Go, Gradle, CocoaPods, Swift Package Manager, pip, uv, Poetry, conda and more.
- A **Projects** section groups `node_modules`, Cargo `target` folders and Python `.venv` folders by project.
- Each item is tagged **Safe** (rebuilds itself), **Review** (costs time or data to restore) or **Keep** (such as the Go module cache, conda packages, simulator devices and Docker's disk image, which are shown but never offered). Safe items are ticked at the start; review items are not.
- Every tag explains what the item is and what regenerates it. Disk Census deletes files itself and never runs a tool's own commands.

### AI Agents

- The space AI coding agents take, by agent: Claude Code and Claude, Codex, Cursor, Windsurf, Zed, Warp, Kiro, Antigravity, Goose and others.
- Old versions, caches, temporary files and logs are offered for cleaning. Each agent's history, settings, credentials, plugins and skills are never offered: history is shown as Keep.
- Of an agent's installed versions, the one its launcher points to, any version running, and the two newest always stay. Nothing a running agent uses is deleted.

### Duplicates

- Finds sets of identical files by their contents, from a minimum size the person picks (10 KB to 100 MB).
- Shows each set's copies side by side, with a thumbnail, folder and date, and what deleting the extras frees.
- Quick picks keep the newest or the oldest copy. The last copy of a set can never be deleted.
- APFS clones, which already share storage, are tagged, since removing them frees little.

### Optimize

- Maintenance tasks, each with what it fixes, what it interrupts, and whether a restart finishes it:
  - rebuild Quick Look's previews and thumbnails;
  - clean up the "Open With" menu (apps that are gone, duplicates);
  - relaunch a stuck Finder;
  - compact Mail's message index, with a backup kept until it checks out;
  - reset font caches;
  - delete local Time Machine snapshots;
  - stop `.DS_Store` files on network and USB drives.
- **One-click Optimize:** the safe clean together with the quick tasks, approved once from one list.

### Empty Trash

- Lists every Trash the person owns: this Mac's, iCloud Drive's, and those on external drives, with their sizes.
- Review the items, then empty all of them or only the ones chosen. Items an app has open stay.
- iCloud Drive items that are only in the cloud are deleted without being downloaded first.

### Widget and background monitor

- A widget in Small, Medium and Large sizes, on the desktop (macOS 14 and later) or in Notification Center (macOS 12 and 13). It shows used space as a ring, how much is safe to clean, recent disk activity, and how used space changed, such as "+12.4 GB (+4%) in 7 days".
- A background monitor (macOS 13 and later) notifies when the startup disk drops under 10% free. It can be turned off in Settings.
- The widget and the monitor never delete anything. The widget's Clean button opens the app's own confirmation.

### Keyboard

- ⌘1 to ⌘7 open Overview, Large Files, Apps, DevTools, AI Agents, Duplicates and Optimize.
- ⌘R scans, ⌘. stops, ⌘O chooses a folder, and ⌘↑ goes up to the enclosing folder.
- No keyboard shortcut ever approves a deletion.

### Command line and AI agents

- `census` is the app's own engine, shipped inside the app, not as a separate download. People see it in the app's CLI and Agents tab and turn it on in their shell from there.
- One license covers both, one update brings both to the same version, and both give the same answers.
- Every command can print JSON for scripts and agents, with stable exit codes and progress updates.
- Disk Census works with any AI agent that can run Terminal commands, such as Claude Code, Codex, Cursor, Gemini CLI, VS Code and Warp.

## How deletion works

- Scanning, browsing and every query are read-only.
- Deleting is permanent. Nothing goes to the Trash, and a deletion can't be undone. Every confirmation says so.
- **Safe** items (caches, build output and logs that apps and tools rebuild) are deleted when the person asks to clean.
- **Review** items are deleted only when the person picks them.
- **Keep** items are shown with their size and never offered.
- Before each deletion, Disk Census checks the item again against a fresh scan. Anything in use by a running app is skipped. Protected, synced, system and Disk Census's own folders are refused.
- Every cleanup writes an audit on the Mac, listing each item and what happened to it.

## Using census as an AI agent

An agent that runs `census` for a person follows these rules:

- Check that it is available with `census version`. If the command is not found, ask the person to turn it on from the app's CLI and Agents tab.
- When the person asks to clean junk, run `census clean --safe --json`. That request is their approval for the safe tier only.
- For anything else (review items, large files, duplicates, apps, the Trash, maintenance tasks), show the person exactly what would be deleted and its size, and wait for an explicit yes.
- Delete only through `census`'s own commands, never with `rm`, Finder or other tools, and never with `sudo`.
- If `census` says it needs a license key, ask the person to activate Disk Census in the app. Never ask for, read or type their key.

```bash
census scan                     # what uses the space, as a short summary
census clean --safe --json      # delete the safe tier, after the person asked to clean
census review --json            # what is left, for the person to choose from
census apply selection.json --json   # delete exactly the paths the person chose
```

Commands:

| Command | What it does |
| --- | --- |
| `scan` | Scans the startup drive, or a folder with `--path` |
| `top`, `ls`, `breakdown`, `types` | The biggest folders and files, one folder's contents, space by category, space by file type |
| `large` | Large files or folders, filtered by size and when they were last opened or modified |
| `findings` | Cleanable items by category and safety tier |
| `apps`, `app`, `leftovers` | Installed apps, one app's data, and apps' leftover data grouped by app |
| `duplicates` | Sets of identical files |
| `clean`, `review`, `apply` | Delete the safe tier; list what needs a person; delete the paths a person chose |
| `uninstall` | Removes an app and its data |
| `maintain`, `optimize` | Maintenance tasks; the safe clean plus the quick tasks |
| `empty-trash` | Lists and empties every Trash |
| `history` | How used space changed over the last hour, day, week and month |
| `access`, `version`, `help` | Full Disk Access status, the version, and help for every command |

## Requirements and getting started

1. Download Disk Census from https://diskcensus.com. It runs on macOS 12 or later, on Apple silicon and Intel Macs.
2. Open it and enter your license key to activate this Mac.
3. Grant Full Disk Access in System Settings › Privacy & Security › Full Disk Access, so the scan can read Mail, Messages, Safari and other protected folders.
4. Scan. Updates come through the app, and bring the app and `census` to the same version.

## License and pricing

- **One-time purchase**, in US dollars. Launch prices by copies sold: $3.99 for the first 100 copies, $4.99 for the next 150 copies, $6.99 for the next 250 copies, then $10. The website shows the current price and how many copies are left at it.
- **Lifetime license**: every future version, with no paid upgrades, on the macOS versions each release supports. There is no subscription and no trial.
- **Up to 3 Macs**: one key covers the app and `census` on up to 3 Macs one person uses, personal or work.
- **Activation and check-ins**: each Mac activates online once, then works offline and checks in at least once every 60 days. Without a valid activation, Disk Census doesn't run.
- **Moving Macs**: a Mac keeps its slot across reinstalls. A slot frees itself after 60 days without a check-in, and support can move a license sooner.
- **Payment**: sold through Link, Stripe's merchant of record. Link takes the payment, handles tax and sends the receipt.
- **Refunds**: a full refund within 14 days if Disk Census doesn't do what the website says it does. Consumers in the UK and the EU also keep their legal right to cancel within 14 days. A full refund or a chargeback ends the license.

## Privacy

- Files and scan results never leave the Mac. Disk Census contacts diskcensus.com only to check for updates and to check the license.
- A license check sends an activation id, a SHA-256 hash of the Mac's hardware id, the Mac's model and the Disk Census version. The key itself is sent only once, at activation. No computer name, user name or file data.
- An update check sends only the Disk Census version. Automatic checks are off unless the person turns them on.
- No analytics and no crash uploads. The website sets no cookies.
- An AI agent that runs `census` reads its output, including file names and paths, and may send it to the agent's own provider.

## Questions

### Is anything deleted automatically?

No. Disk Census deletes only the items you select, after you confirm. Deleted items skip the Trash, so the confirmation is your last check.

### How does it know what’s safe to delete?

Each item is tagged Safe if it rebuilds itself, Review if getting it back would cost you time or data, or Keep. Keep items are shown but never offered for deletion.

### Which Macs does it run on?

Any Mac with macOS 12 Monterey or later, Intel or Apple silicon.

### Do I need to scan again for each view?

No. One scan fills every view. Later scans only read what changed.

### Does it clean up Xcode and other developer files?

Yes. It finds caches and build files from Xcode, Homebrew, npm, Yarn, pip, Cargo and many other tools, grouped by tool. A few, like Docker’s disk image, are shown with their size but kept.

### Can my AI agent use it?

Yes. The census command comes with the app. Your agent can read everything, clear the safe items when you ask, and needs your OK for anything else.

### Does it remove every trace of an app?

It removes the files it can clearly tie to the app. Anything it isn’t sure about is shown but left unticked.

## Contact

- Made by Moiz (https://x.com/moz_281), in London.
- Support: support@diskcensus.com, answered within 48 hours.
- [License Agreement](https://diskcensus.com/terms)
- [Privacy Policy](https://diskcensus.com/privacy)
- [Refund Policy](https://diskcensus.com/refunds)