tw93/Mole: a terminal toolkit for Mac cleanup, uninstalling and disk analysis

The gap Mole fills on a Mac that only has a terminal

macOS ships with no supported way to reclaim space from the command line. You can delete ~/Library/Caches by hand, but you have no list of which apps are gone and which files they left behind, no size estimate before you delete, and no record of what you removed. Mole targets that gap. The README describes it as combining CleanMyMac, AppCleaner, DaisyDisk and iStat Menus in a single binary, and the command list backs the claim: mo clean, mo uninstall, mo optimize, mo analyze, mo status, mo purge, mo installer, plus mo touchid for configuring Touch ID with sudo.

The intended user is a developer or sysadmin on macOS who is comfortable typing commands and reading output. The README is explicit that Mole is built for macOS, with an experimental Windows version on a separate branch. There is no Linux build documented. If you are looking for a Linux cleaner, this is not it.

A Go binary, a shell CLI and a log file

The repository layout is mixed. Top-level entries include bin/, cmd/, internal/, lib/, mo, mole, install.sh, a Makefile, and both go.mod and go.sum. The Makefile builds two Go binaries from ./cmd/analyze and ./cmd/status, producing bin/analyze-go and bin/status-go for the local architecture, with release targets for darwin/amd64 and darwin/arm64. CGO_ENABLED=0 is set for release builds, and the Makefile comment states this keeps the macOS SDK on the release runner from raising the Mach-O minimum OS version via cgo. So the disk analyzer and the live status dashboard are Go programs; the rest of the toolkit is shell.

The dependencies in go.mod tell you what the Go side relies on: bubbletea and lipgloss for the terminal interface, gopsutil for system metrics, xxhash and golang.org/x/sys. That is a small dependency set for a tool that reads CPU, GPU, memory, disk and network counters.

Data flow is file-oriented. Cleanup activity is appended to ~/Library/Logs/mole/operations.log, which mo history reads back, and mo history --json emits the same record as JSON. Whitelist selections persist in ~/.config/mole/whitelist. Those two paths are the entire state model described in the README, which is a point in Mole's favour: you can inspect and back up everything it remembers.

Installing Mole and running a first dry-run

The README gives two install paths. Homebrew is the short one:

brew install mole

If Homebrew no longer supports your macOS version, the README points to the install script instead:

curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash

The script normally installs to /usr/local/bin, which can prompt for an administrator password. The README offers a user-owned prefix if you want future mo update runs to stay password-free:

mkdir -p "$HOME/.local/bin"
curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s -- --prefix "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"

Add that PATH export to ~/.zshrc for new terminals. Mole updates the installation you invoked, so it keeps using this directory; commands that change system-owned files may still request administrator access.

Once installed, the README's own advice is to preview before deleting. Every destructive command has a dry-run flag:

mo clean --dry-run
mo clean --dry-run --debug
mo history

You should see a list of eligible paths with sizes and skip reasons before anything is removed. The README notes that available items, sizes and skip reasons depend on your Mac, so the output will not match the sample in the README exactly. After a real run, mo history shows what was tracked; mo history --json gives the same as JSON.

What the safety model does and does not cover

Mole deletes files, and the README is direct about it. It validates paths, protects shared and system-owned locations, and asks for confirmation when an action needs it. When Mole cannot prove an item is safe to change, it skips or refuses it. The sample mo clean output shows this in practice: a pnpm cache line reads "skipped (pnpm busy)", and an Xcode runtime volume line reports "removed 2, 3 in use". Those skip reasons are the most useful part of the output, because they tell you what Mole declined to touch and why.

The uninstaller has a narrower rule than you might expect. It removes an app plus related files it can tie back to that app, and keeps shared data when another installed copy still uses it. That is a conservative design, and it means leftovers from a long-gone app are better handled by mo clean, which the README explicitly recommends for that case.

Two limits are worth stating plainly. First, the README points to SECURITY.md and SECURITY_AUDIT.md for safety boundaries and current limitations, which is an admission that the boundaries are documented rather than eliminated. Second, operation logging can be turned off with MO_NO_OPLOG=1. If you disable it, mo history has nothing to read, and you lose the only audit trail the tool provides. That trade-off is yours to make, but make it deliberately.

Where Mole is the wrong tool

Mole assumes macOS. The README says so, and the only non-macOS artifact described is an experimental Windows branch that the README itself labels experimental. If your fleet is Linux, Mole is not a candidate, and the search interest in a Linux version has no documented answer in the README.

It also assumes you want a CLI. The README positions a separate native app, Mole for Mac, as the alternative for people who prefer a GUI, sold with one license covering 2 Macs, lifetime updates and a 14-day refund. That is a commercial product with its own pages, not a mode of the free binary. If you need a graphical interface and will not pay, Mole is the wrong fit.

A third case: if you want a tool that never asks for an administrator password, the Homebrew and default script installs may not suit you. The README says the script normally installs to /usr/local/bin and may prompt for a password, and that commands touching system-owned files may still request administrator access even from a user-owned prefix. Mole cannot promise a password-free existence.

How Mole differs from a general-purpose cleaner

The obvious comparison is CleanMyMac, which appears in the search questions and in Mole's own README framing. The difference in approach is not just price. CleanMyMac is a closed-source GUI application; Mole's CLI is GPL-3.0 and its behaviour is inspectable in the repository, including a Makefile that builds the Go components and a documented log at ~/Library/Logs/mole/operations.log. If you want to know what a cleaner will delete before it deletes it, a dry-run flag plus a readable log is a different proposition from a GUI's confirmation dialog.

The closer comparison for the uninstall half is AppCleaner, which the README also names. AppCleaner is a drag-and-drop GUI for removing an app and its support files. Mole's mo uninstall does the same job from a terminal, with --dry-run to review the plan and a rule about keeping shared data that another installed copy still uses. If you already script your machine setup, having uninstall in the same binary as cleanup and disk analysis removes a context switch.

For disk visualization, DaisyDisk is the reference point the README invokes. Mole's mo analyze is a visual disk explorer that can take a path, so mo analyze /Volumes restricts it to external drives and mo analyze /private/tmp reviews user-owned temporary directories. The README states that mo analyze moves selected items to Trash after confirmation, which is a gentler default than permanent deletion.

Licence, updates and what maintenance looks like

Mole is GPL-3.0. The practical consequence for most users is that the CLI stays free and open source, which the README states directly, while the native Mac app is a separate paid product. If you fork Mole or ship it inside a product, GPL-3.0 obligations apply, and the repository also carries a TRADEMARK.md, so the name and marks are handled separately from the code licence. That is a question for your own legal review, not something this article can settle.

The last push to the default branch was on 2026-08-22, and the most recent release, V1.52.0, carries the same timestamp. A Windows-tagged release, v1.30.0-windows, appeared on 2026-08-16, and V1.51.0 on 2026-08-16. The release cadence documented in the repository is frequent, with version numbers in the 1.5x range.

Upgrade cost is low by design. The install script accepts a specific release tag, with or without the leading V, so you can pin:

curl -fsSL https://raw.githubusercontent.com/tw93/mole/main/install.sh | bash -s -- 1.51.0

The README warns that passing main installs unreleased code from the default branch, so expect rough edges, and that latest still works as a legacy alias for main despite the name. That naming is a trap worth remembering: latest does not mean newest stable. Building from source is also possible, with make build producing the two Go binaries into bin/, and make verify running the shell checks and go test ./... together.

Editorial conclusion

Adopt Mole if you already live in a terminal and want cleanup, uninstall and disk analysis under one command, with --dry-run and mo history as your safety net. Skip it if you want a GUI, if you are not on macOS, or if you cannot accept that the project's own SECURITY_AUDIT.md describes current limitations. Before your first real deletion, run mo clean --dry-run --debug, read ~/Library/Logs/mole/operations.log after the first pass, and decide whether MO_NO_OPLOG=1 fits your audit needs.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes