MacDoctor by Faisal

Understand what is using your Mac storage, why it exists, and what is safe to remove.

Secondary promise: Clean your Mac without breaking your development environment.

MacDoctor is a native macOS app for cleaning caches, analyzing storage, uninstalling applications, and checking system health — built with a developer-first safety philosophy: it never touches node_modules, Docker, Xcode projects, .git, .env, or lockfiles without your explicit, per-item confirmation.

Created by Faisal Al Anqoudi.

Not affiliated with, endorsed by, or a copy of any existing Mac cleaning product. All design, code, wording, and branding are original.

Download & Install

App (with a window, buttons, click-to-clean):

1. Go to Releases and download MacDoctor.dmg
2. Open it and drag MacDoctor to Applications. Signed and notarized releases open normally; unsigned development releases also include an explicitly-labelled compatibility installer.

Terminal tool (type commands, no windows):

1. Go to Releases and download macdoctor-cli.zip
2. Unzip it, then in Terminal run:

   cd ~/Downloads
   xattr -cr macdoctor
   ./macdoctor

That's it. If macOS still complains the file "can't be verified," see Trouble opening it? below.

Features

• Storage Intelligence / Explain Why This Exists — rule-backed ownership, regeneration, impact, safety, confidence, command preview, and recovery information in both SwiftUI and the terminal.
• Project detection — finds common project types from marker file names under configured roots without reading manifest or source contents.
• Smart Scan — one scan across logs, Trash, browser caches, and developer package-manager caches, with live progress.
• Safe Cleanup — known-disposable logs/caches only, explicit rules, no blind directory walks.
• Browser Cleanup — cache/code-cache/GPU-cache only, for Safari, Chrome, Arc, Brave, Edge, and Firefox. History, cookies, passwords, bookmarks, and profiles are never touched.
• Developer Cleanup — package-manager download caches (Homebrew, npm, Yarn, pnpm, CocoaPods, uv, pip, Bun, node-gyp, SwiftPM, Playwright, Hugging Face, Codex, OpenCode), plus a read-only node_modules size audit and a read-only Docker audit. Nothing developer-related is deleted automatically.
• App Uninstaller — bundle-ID-based related-file detection with Confirmed/Likely/Possible confidence; only Confirmed items are pre-selected.
• Large Files — size/age-filtered explorer over your chosen folders.
• System Data & System Health — honest explanations, real facts, no invented "health score" or fake optimization claims.
• Activity History & Quarantine — every cleanup moves items to a recoverable Quarantine folder first (default 7-day retention), with one-click restore.
• Arabic + English, full RTL support, a name-personalized greeting, and optional light jokes that never hide a real warning or error.

Safety philosophy

1. Scan before delete, always. Preview exact paths, sizes, and risk levels.
2. Nothing is permanently deleted directly — cleanup moves items to Quarantine first.
3. A fixed, explicit list of protected paths (~/Documents, ~/.ssh, .git directories, lockfiles, Xcode/Android projects, Docker volumes, Keychains, browser profiles, and more) can never be touched.
4. Advanced/developer categories (node_modules, Docker, DerivedData) are never pre-selected and, in this release, are audit-only.
5. Runs 100% locally. No analytics, no telemetry, no uploads of file names, paths, or scan results.

See AGENTS.md for the full technical safety-rule breakdown.

Trouble opening it?

macOS blocks apps that aren't signed with a paid Apple Developer certificate (this project doesn't have one yet) — it's not a sign anything is wrong with the download.

• Unsigned development app: use the compatibility installer included in that DMG, or right-click the app and choose Open. Official signed and notarized releases should never require disabling Gatekeeper or stripping quarantine attributes.
• CLI: run xattr -cr macdoctor in the folder where you unzipped it (already in the steps above).

Once a Developer ID certificate is configured in this repo's release secrets (see RELEASING.md), this step won't be needed.

Terminal tool commands

Running macdoctor with no arguments opens the interactive dashboard shown above. For scripting, each screen also has its own command:

macdoctor scan              # see what's there
macdoctor scan --json         # stable machine-readable output
macdoctor scan --format yaml  # automation-friendly YAML
macdoctor explain ~/.cache/uv # why it exists and deletion impact
macdoctor developer           # developer caches + Docker risk separation
macdoctor projects            # project markers under common roots
macdoctor project inspect .   # per-project storage + running processes
macdoctor doctor              # storage and developer diagnosis
macdoctor doctor --json       # versioned diagnosis report
macdoctor clean --safe --dry-run # exact non-destructive preview
macdoctor clean --safe        # move Safe items to Quarantine
macdoctor system-data         # honest category explanation
macdoctor history             # local activity
macdoctor config              # shared app/TUI/CLI settings
macdoctor health              # real system facts
macdoctor large-files          # size/age-filtered large file scan
macdoctor apps list             # installed applications
macdoctor apps leftovers <id>    # related files for one app, by bundle ID
macdoctor quarantine list         # what's currently quarantined
macdoctor quarantine restore <id>  # undo a cleanup
macdoctor completion zsh          # zsh/bash/fish completion

Building from source

git clone https://github.com/<org>/macdoctor.git
cd macdoctor
swift build
swift test
swift run MacDoctorApp     # GUI app
swift run macdoctor scan   # CLI

Note: swift run MacDoctorApp is fine for coding, but skips app packaging (Info.plist, bundled resources) — localized text won't render, since that's normally read from the packaged .app. To see the real, finished experience, run Scripts/build-release.sh and open the resulting dist/MacDoctor.app.

See BUILDING.md for release-build and DMG instructions, and COMMANDS.md, TUI.md, and DEVELOPER_STORAGE_RULES.md for feature details.

Website

The bilingual landing page lives in website/ and has no build dependencies. Connect this repository to Netlify; netlify.toml sets that folder as both the static-site base and publish root (so Netlify does not try to install Swift) and maps /download to the latest GitHub Release.

For a local preview:

python3 -m http.server 4173 --directory website

Permissions

MacDoctor works without any special permission for most features. Some deeper scans may benefit from Full Disk Access, which you can grant later from Settings → the in-app Permission Center. MacDoctor never requests a permission a currently-active feature doesn't need.

Privacy

Everything runs locally. See PRIVACY.md.

Limitations (current release)

• No deletion path yet for node_modules/Docker (audit only).
• Some high-risk developer data (Gradle/Maven dependencies, Xcode archives, simulators, Android SDK, Ollama) is intentionally read-only/audit-only.
• Docker inspection reports verified aggregate classes plus named volumes and conservative purpose hints; volumes remain Protected and audit-only.
• TUI scanning is cancellable and incremental, but exact percentage and pause are not shown because the current scanners cannot report a truthful total.
• No menu bar item or launch-at-login toggle yet.
• Distributed unsigned unless the maintainer has configured notarization secrets.

See PLAN.md for the full backlog.

Roadmap

• Xcode/Android/Gradle/Rust/Go developer scanners
• Menu bar quick actions
• Signed & notarized releases

Contributing

See CONTRIBUTING.md. Please read the safety rules in AGENTS.md before submitting anything that touches MacDoctorCore/Safety or MacDoctorCore/Cleanup.

License

GPL-3.0 — see LICENSE.

Acknowledgments

Built with Swift, SwiftUI, and Swift Package Manager. Thanks to everyone who tests, files issues, and contributes.

---

Created by Faisal Al Anqoudi