dustloft

KO | EN

gitlite — search

#sql #claude-code #typescript #svg #video #agent #mysql #hacktoberfest #golang #automation

(★ 9)

Native macOS disk cleanup with a safety-first model — never deletes what you cannot get back without asking

File Explorer

ZIP Download

- - release.yml
  - site-api.yml
  - site-responsive.yml
- - _lua.mjs
  - _store.mjs
  - ping.mjs
  - stats.mjs
- - _shared.css
  - docker-raw-taking-up-space-mac.html
  - find-large-files-mac-terminal.html
  - free-cleanmymac-alternatives.html
  - git-repositories-taking-up-space.html
  - how-to-clear-system-data-mac.html
  - index.html
  - is-it-safe-to-delete-library-caches.html
  - node-modules-taking-up-space-mac.html
  - purgeable-space-mac.html
  - whatsapp-messages-media-mac.html
  - why-is-system-data-so-large-on-mac.html
  - xcode-derived-data-simulators.html
- - cleanmymac.html
- - bricolage-grotesque-latin-ext.woff2
  - bricolage-grotesque-latin.woff2
- - apple-touch-icon.png
  - mark-v3.png
  - overview.png
  - overview.webp
  - review.png
  - review.webp
- .gitignore
- .vercelignore
- 404.html
- 59788e4e72f535fa09b1c49b5cd13a61.txt
- index.html
- llms-full.txt
- llms.txt
- privacy.html
- robots.txt
- safety.html
- sitemap.xml
- stats.html
- vercel.json
- - Cleaner.swift
  - DesignSystem.swift
  - DustloftApp.swift
  - Metrics.swift
  - Models.swift
  - OperationLog.swift
  - Permissions.swift
  - SafePath.swift
  - Scanner.swift
  - ScannersApps.swift
  - ScannersMedia.swift
  - ScannersUser.swift
  - Settings.swift
  - Shell.swift
  - Updater.swift
- - MetricsTests.swift
  - ParsingTests.swift
- - run.mjs
  - run.sh
  - shim.mjs
- - check.mjs
  - run.sh
  - serve.mjs
- deploy-site.sh
- indexnow.sh
- make-llms-full.py
- make_dmg.sh
- make_icon.swift
- setup_signing.sh
- site-sitemap.sh
- winid.swift
.gitignore
build.sh
DOCFILES.md
install-online.sh
install.sh
LICENSE
Package.swift
README.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Dustloft</h1>

<p align="center">
  <b>Find out what is actually eating your Mac's disk — and get it back safely.</b><br>
  A native macOS app that never deletes anything you cannot get back without telling you first.
</p>

---

## Why

macOS reports tens or hundreds of gigabytes as "System Data" and gives you no way
to look inside it. Dustloft opens that box: it measures every real consumer of
space, sorts them by how recoverable they are, and makes you confirm before
anything is removed.

It was built after a manual cleanup took one 512 GB Mac from **20 GB free to
215 GB free** — and after that cleanup nearly destroyed a git repository whose
history existed nowhere else. Both the findings and the near-miss are baked into
the app's rules.

## Safety first

Dustloft sorts everything it finds into three tiers:

| Tier | Meaning |
|---|---|
| **Regenerable** | Comes back on its own — caches, build output, dependencies, Docker images |
| **Needs admin** | Safe to remove, but macOS asks for your password once |
| **Permanent** | Nothing rebuilds it. Never bulk-selected, needs a separate confirmation, and is moved to the Trash rather than deleted outright — except for something already in the Trash, which has nowhere further to go, and which the confirmation says will be deleted for good |

And it refuses, by design, to:

- delete a `.git` directory — it offers `git gc` only, and warns in red when a repo's history exists nowhere but your disk
- touch Dropbox, iCloud Drive or any synced folder, where a local delete propagates everywhere
- remove Docker volumes
- touch your MySQL data directory
- claim it can reclaim "purgeable" space, which no third-party app can reliably free
- delete inside `/System`, `/usr`, `/bin`, `/etc`, `/var`, `/private` or any other
  protected system tree, at any privilege level
- follow a symlinked parent folder into a protected location — the parent is
  canonicalised and the refusal list re-checked against the resolved path

Every removal is appended to `~/Library/Logs/Dustloft/operations.log` — timestamp,
action, size and full path, tab separated. That file stays on your machine and is
never uploaded, in whole or in part.

## What Dustloft sends, and what it does not

Nothing about the contents of your disk ever leaves it. No file name, no path, no
directory listing, no account, no email address.

Dustloft does send one anonymous line — when the total below changes, and once a
day even when it has not — so there is some idea of how many Macs it runs on and
whether it has actually given anyone their disk back. That line is the whole of
it:

```json
{ "id": "9f2c1e7a-…", "cleaned": 41203847610, "version": "1.0.27" }
```

- `id` is a random UUID this copy of the app generated for itself on first use.
  It is not derived from your hardware, your network, your account or anything
  else, and it is created only if something is actually going to be sent.
- `cleaned` is the running total of bytes Dustloft has reclaimed on this Mac.
- `version` is the build you are running.

`cleaned` counts items sent to the Trash as well as those deleted outright — you
asked for both to go — which is why everything shown against this figure says
"cleaned" rather than "freed". Each item counts once, at the moment it leaves
the active filesystem, and never again when the Trash is emptied.

The request's IP address is used to rate limit, and only that. A salted hash of
it becomes a counter that expires after sixty seconds; the address itself is
never written down, and neither the hash nor the address is attached to a report
or stored alongside one. By default the salt is random per server process, so
those short-lived counters cannot be matched up across processes or after a
restart. The figures all this feeds are public at
**[dustloft.com/stats](https://dustloft.com/stats)**; there is no endpoint, there
or anywhere, that returns a single install's row.

**Offline.** Dustloft does not need a network for anything it actually does —
scanning, measuring and cleaning are entirely local, and a report that cannot be
sent fails silently without holding anything up. The total is cumulative rather
than a stream of events, so nothing is lost by a report not landing: whatever
one attempt could not send, the next one carries. The app also watches for the
network coming back and reports then, so a laptop that reclaimed 40 GB on a
plane is counted when it reconnects rather than whenever it next happens to be
opened.

**Turning it off.** The first-run card shows the message above with your real
numbers in it, and has a "Turn it off" button. The switch stays in the Overview
footer afterwards. To disable it before the app is ever launched:

```bash
launchctl setenv DUSTLOFT_NO_METRICS 1
```

Turning it off stops it permanently — there is no final report on the way out.

**The website is a separate matter.** dustloft.com runs Microsoft Clarity, which
is ordinary website analytics and has nothing to do with the app — installing
Dustloft does not opt you into it. It is described on
[the privacy page](https://dustloft.com/privacy).

The code is worth more than the paragraph: [`Sources/Dustloft/Metrics.swift`](Sources/Dustloft/Metrics.swift)
is the entire client, and the payload is pinned by a test that fails if a fourth
field is ever added.

## Install

### One command (recommended)

```bash
curl -fsSL https://raw.githubusercontent.com/kapil303196/dustloft/main/install-online.sh | bash
```

This downloads the latest release, installs it, and opens it. Use this if you
want it to just work.

### From the DMG

**[Download the latest release](https://github.com/kapil303196/dustloft/releases/latest)**
— one universal build that runs natively on Apple Silicon and Intel. Drag
Dustloft to Applications.

macOS will then say it **"could not verify this app is free from malware"**.
That is expected and is not a claim that anything was found. It means the build
is not *notarised* by Apple, which requires a paid Apple Developer Program
membership ($99/year). There is no free tier that grants a Developer ID
certificate or access to notarisation.

To open it anyway on **macOS 15 or later** — note that Control-click → Open no
longer works, Apple removed that:

1. Try to open Dustloft once and let it be blocked.
2. Go to **System Settings → Privacy & Security**, scroll down, and click
   **Open Anyway** next to the message about Dustloft.

Or in Terminal:

```bash
xattr -dr com.apple.quarantine /Applications/Dustloft.app
```

The one-command installer above avoids all of this, because macOS applies the
quarantine flag to browser downloads, not to `curl`.

Each release also publishes a `.sha256` file if you want to verify the download.

### From source

```bash
git clone https://github.com/kapil303196/dustloft.git
cd dustloft
./tools/setup_signing.sh    # optional, see below
./build.sh && ./install.sh
```

Needs only the Xcode Command Line Tools — no full Xcode install.

### Why `setup_signing.sh` exists

macOS ties Full Disk Access to an app's **code signature**. An ad-hoc signature
changes on every build, so each rebuild silently revokes the permission you
granted — and macOS quietly falls back to nagging you for Desktop and Downloads
access instead. This creates a stable local identity so the grant survives
rebuilds. Only needed when building from source.

### Full Disk Access

Dustloft asks for this on first run and explains why. Two things worth knowing:

- macOS applies the permission **only to a freshly launched process**, so
  Dustloft has to relaunch once after you grant it. It offers a button to do so.
- If you rebuild the app with a different signature, you must remove Dustloft
  from the Full Disk Access list and re-add it.

## Updating

Dustloft checks GitHub Releases on launch. When a newer build exists it offers
**Update now**, which downloads the DMG, mounts it, replaces the installed app
and restarts. **Check for Updates…** in the Dustloft menu does the same on
demand, and the running version is shown at the bottom of the Overview.

Every push to `main` builds a universal DMG in CI and publishes it as a release,
so there is always something to update to.

## What it looks at

**Every installed app, discovered dynamically** — no hardcoded list. Dustloft
measures each app's data, resolves folder names to real app names, and separates
an app's actual content from its disposable caches, so whatever happens to be
hoarding space on *your* Mac shows up on its own.

Alongside that: the Trash, old downloads, leftovers from uninstalled apps,
forgotten screen recordings, video-editing scratch caches, virtual machine
images, device backups, mail attachments, browser caches, offline media, and
Messages attachments — plus the developer set (node_modules, build output,
package stores, Docker, local LLM models, Xcode leftovers, Node runtimes and
oversized git repositories), which only appears when such things are found.

Scans are cached between launches, so opening Dustloft is instant and a full
rescan only happens when you ask or once results are genuinely stale.

## Contributing / continuing this work

Read [`DOCFILES.md`](DOCFILES.md) first. It carries the full context: why each
rule exists, the architecture, the threading model, and the known gaps.

## License

MIT

dustloft

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README