mac-cleaner

macOS storage and memory cleanup tool — available as a menu bar GUI or a terminal CLI.

Quick start (no install)

# CLI — interactive terminal cleaner
npx @phamyqb/mac-cleaner

# GUI — floating menu bar app
npx @phamyqb/mac-cleaner --gui

Install globally

npm install -g @phamyqb/mac-cleaner

Then run any time:

mac-cleaner        # CLI
mac-cleaner --gui  # GUI

Global install works identically to npx — Electron and all dependencies are bundled with the package.

Note: The Launch at login setting requires a global install. When running via npx, the toggle is disabled because npx caches are temporary and the registered path would break after a cache clear.

GUI features

The menu bar icon shows live RAM usage (9.2G 38%). Click it to open the HUD:

| Tab | What it does | |-----|-------------| | RAM | Live memory gauge, pressure level, top apps by usage, one-click Optimize Memory | | Processes | Process list sorted by memory, kill any process | | Disk | Disk usage bar, cache categories with sizes, auto-rescan, one-click clean | | Settings | Launch at login, auto-clean threshold, auto-clean toggle, notifications, disk rescan interval |

The window appears below the menu bar icon and hides automatically when you click away.

On first Optimize, mac-cleaner prompts once for your password to enable passwordless purge — never asked again.

CLI usage

mac-cleaner [options]

Options:
  -h, --help    Show help
      --gui     Launch the menu bar GUI

Space to toggle items, Enter to confirm.

• Green [safe] — caches regenerated automatically
• Yellow [situational] — asks for confirmation

Development

git clone https://github.com/phamyqb/mac-cleaner
cd mac-cleaner
npm install
npm link              # install locally as global binary
npm test              # run unit tests
npm run build:renderer # build the React renderer (Vite)
npm run gui           # build + launch GUI locally

Add a new disk category

Edit src/categories.js to add a category object, then add its cleaner function to src/cleaners.js.

Uninstall

npm uninstall -g @phamyqb/mac-cleaner