Documentation

Last updated · August 2026

Overview

Sweepr is two interfaces sharing one cleaning engine. The CLI is free, open source, and MIT-licensed. The Mac app is a native SwiftUI companion for $9 lifetime. Five tools are shared between them; the CLI adds a few terminal-only commands.

Mac App

Clean (Earth)

Scans eleven categories: app caches, browser temp files, developer tools (Xcode, npm, pip), AI tools (ChatGPT, Claude, Copilot), communication apps (Discord, Slack), cloud storage, design tools (Adobe, Figma cache), system logs, miscellaneous temp files, and .DS_Store. The Trash is listed separately at the end.

The review list is sorted by deletion impact: regenerable caches appear first, user-visible state last, Trash always at the bottom. Hardlink-aware sizing means files shared across tools (uv, pnpm) are not double-counted. Default deletion is permanent so the freed bytes match the headline. One toggle in Settings routes everything through the system Trash instead.

Uninstall (Mars)

Pick apps to remove. Sweepr finds leftover files in fifteen-plus Library subdirectories: Application Support, Caches, Preferences, Logs, Launch Agents, Launch Daemons, Login Items, Containers, Group Containers, Saved Application State, and more. Dock entries (persistent apps, persistent others, recent apps) are cleaned automatically.

Root-owned apps ask for your password once per session; subsequent removals run silently. About fifty system-critical bundles are hidden so they cannot be selected. Vendor security and antivirus apps show a link to the vendor's own uninstaller instead. Anything that looks like personal data gets a warning before deletion.

Optimize (Mercury)

Twenty-two safe maintenance tasks, executed with one tap. Non-admin tasks run silently. Admin tasks prompt once and then run in batch.

Tasks include: rebuild Quick Look, Spotlight, font cache, and Launch Services; vacuum SQLite stores; flush DNS; prune notification history; repair broken preference files; clean quarantine database; prevent .DS_Store on network volumes; remove broken Launch Agents and shared file lists.

Safety gates skip tasks when conditions are unsafe: Bluetooth reset is skipped when external audio devices are connected, font cache rebuild is skipped when browsers are open, Spotlight reindex is skipped on battery power, and network stack flush is skipped when a VPN is active.

Analyze (Jupiter)

A treemap visualization of your entire disk. Drill down into any directory to see size at every level. Right-click any entry to move it to the Trash or reveal it in Finder, without leaving the map view.

Entries that could not be sized (permission-restricted folders, TCC-gated containers) are surfaced with a retry option instead of being silently dropped. Protected navigational roots (/, /Users, /Applications) cannot be trashed. Disk scan results are cached for 24 hours for fast re-entry.

Status (Sun)

Nine metrics on one bento grid, each with a sixty-second sparkline: CPU, memory, GPU, disk I/O, network throughput, battery status, thermal state, uptime, and a health score (0-100).

The process list below the grid updates every second. Click any column header (Name, CPU, Memory) to sort. Click a row to pin it; pinned processes stay at the top across refreshes so you can watch a specific app without losing it in the scroll.

Doctor

From the menu bar: Help → Run Doctor…. Sweepr gathers a short diagnostic report covering your Mac model, macOS version, permissions, recent operations, and environment. Click Copy Report to paste it into a chat, or Open GitLab Issue to land in a bug form with the report pre-filled.

Doctor detects five conditions: missing Full Disk Access, elevated memory pressure, disk usage above 90%, unwritable operations log, and recent operation failures. Each condition links to a help article with resolution steps. See the Help page for details on each.

Settings

Planet Landing: toggle the animated planet intro on each tab. When off, tabs open directly to their tool. Delete mode: choose between permanent deletion (default for caches) and Trash routing. Full Disk Access: a shortcut to open System Settings. License activation: press Cmd + Shift + L or use the Sweepr menu.

CLI

Installation

Via Homebrew: brew install mole. Via script: curl -fsSL https://gitlab.com/sweepr/sweepr-cli/-/raw/main/install.sh | bash. Run mo for the interactive menu, or any subcommand directly.

Shared commands (also in the Mac app)

mo clean

Deep cleanup across the same eleven categories as the Mac app. Supports --dry-run to preview without deleting, --debug for detailed logs, and --whitelist to manage protected caches. Skips caches of running apps automatically.

mo uninstall

Interactive app selection with remnant detection. Shows app size, bundle ID, and last-used date. Finds the same fifteen-plus leftover categories as the Mac app. Supports --dry-run.

mo optimize

Runs the same twenty-two maintenance tasks. Admin tasks prompt for your password. Supports --whitelist to exclude specific tasks from future runs.

mo analyze

Interactive treemap in the terminal. Navigate with arrow keys or Vim bindings (h/j/k/l). Trash files directly from the map. Supports --json output and custom paths like mo analyze /Volumes for external drives.

mo status

Live system dashboard: CPU, GPU, memory, disk I/O, network, battery, thermals, uptime, health score, and top processes with sixty-second sparklines. Supports --json for piping to other tools.

CLI-only commands

mo purge

Finds old build artifacts across project directories: node_modules, target, .build, build, dist, venv. Scans configurable paths (default: ~/Projects, ~/GitHub, ~/dev). Projects younger than 7 days are marked "Recent" and unselected by default. Supports --dry-run and --paths to configure scan directories.

mo installer

Discovers .dmg, .pkg, and .zip installer files in Downloads, Desktop, Homebrew cache, iCloud, and Mail attachments. Labels each file by source location. Supports --dry-run.

mo touchid

Enables Touch ID for sudo commands. Run mo touchid enable to configure, mo touchid disable to revert. Supports --dry-run.

Utility commands

mo completion

Sets up shell tab completion for Bash and Zsh. Auto-detects your shell and updates the appropriate config file.

mo update

Self-update to the latest stable release. Use --nightly for the latest unreleased build from main (script installs only). Use --force to reinstall the current version.

mo remove

Uninstalls Sweepr CLI from your system, including config files and shell integration. Supports --dry-run.

Safety

Both the CLI and Mac app share the same safety principles:

Path protection. A built-in deny list covers system-critical directories, your home folder's essential structure, and anything outside known cache locations. Symlinks are resolved and validated before any operation.

Process awareness. Caches belonging to running apps are skipped during cleanup. Browser caches are not touched while the browser is open.

License gate. In the Mac app, all destructive operations (clean, uninstall, optimize, trash from Analyze) require an active license. Scanning is always free.

Whitelist. Both the CLI (~/.config/mole/whitelist) and Mac app let you protect specific caches or optimization tasks from future runs.

Operations log. Every deletion is recorded at ~/Library/Logs/mole/operations.log. The Mac app's Doctor overlay checks the health of this log and surfaces any recent failures.

Preview first. The CLI supports --dry-run on every destructive command. The Mac app shows the full file list and byte count before any action.

Troubleshooting

The Mac app includes a built-in Doctor that detects common issues. Open it from Help → Run Doctor… in the menu bar. For specific conditions, see the Help page.

For the CLI, add --debug to any command for detailed logs. Review the operations log at ~/Library/Logs/mole/operations.log for recent activity. If a command fails silently, check whether Full Disk Access is granted in System Settings.

To report issues, see the Report a problem section on the Help page.