{"id":51465080,"url":"https://github.com/vstorm-co/mac-clean","last_synced_at":"2026-07-06T10:01:03.337Z","repository":{"id":368377411,"uuid":"1284846562","full_name":"vstorm-co/mac-clean","owner":"vstorm-co","description":"Auditable, open-source macOS disk cleaner with a local GUI. Scan, review, and you approve every deletion. Zero runtime dependencies, Trash by default, nothing leaves your machine.","archived":false,"fork":false,"pushed_at":"2026-06-30T09:06:38.000Z","size":9589,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-30T10:27:08.540Z","etag":null,"topics":["cache","cleaner","cli","disk-cleanup","disk-space","gui","mac","macos","nodejs","open-source","privacy","self-hosted","typescript","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://vstorm.co","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vstorm-co.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-30T08:48:09.000Z","updated_at":"2026-06-30T09:08:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vstorm-co/mac-clean","commit_stats":null,"previous_names":["vstorm-co/mac-clean"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vstorm-co/mac-clean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fmac-clean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fmac-clean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fmac-clean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fmac-clean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vstorm-co","download_url":"https://codeload.github.com/vstorm-co/mac-clean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fmac-clean/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35185688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","cleaner","cli","disk-cleanup","disk-space","gui","mac","macos","nodejs","open-source","privacy","self-hosted","typescript","zero-dependencies"],"created_at":"2026-07-06T10:01:01.484Z","updated_at":"2026-07-06T10:01:03.325Z","avatar_url":"https://github.com/vstorm-co.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003emac-clean\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/mac-clean-demo.gif\" alt=\"mac-clean demo\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eYour own, auditable macOS disk-cleanup tool with a local GUI.\u003c/b\u003e\u003cbr\u003e\n  Scan your Mac for wasted space, review it, and approve every deletion yourself.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-safety-by-design\"\u003eSafety\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-install\"\u003eInstall\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-usage\"\u003eUsage\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-categories\"\u003eCategories\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#-how-it-works\"\u003eHow it works\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-macOS-000000?logo=apple\u0026logoColor=white\" alt=\"macOS\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Node.js-18+-339933?logo=nodedotjs\u0026logoColor=white\" alt=\"Node 18+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript\u0026logoColor=white\" alt=\"TypeScript\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/runtime%20deps-0-2ea44f\" alt=\"Zero runtime dependencies\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\n\u003c/p\u003e\n\n---\n\n## Why\n\nMost Mac cleaners are closed black boxes you have to *trust* with your whole disk.\n**mac-clean is the opposite.** It has **zero runtime dependencies** — only Node.js\nbuilt-ins ever touch your filesystem — so you can read every line that runs. It never\ndeletes anything on its own: it scans, groups what it finds, and waits for **you** to\npick exactly what goes. The default action moves files to the Trash, so mistakes are\nrecoverable.\n\n\u003e Built as a self-hosted alternative to third-party cleaners — nothing leaves your machine, nothing runs without your click.\n\n---\n\n## 🛡️ Safety by design\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003e👀 Read-only scanning\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003eScanning never deletes or modifies anything. It only measures sizes.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003e🗑️ Trash by default\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003eDefault action moves items to the macOS Trash via native \u003ccode\u003eNSFileManager\u003c/code\u003e — fully recoverable. Permanent delete is a separate, double-confirmed action.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003e✅ You approve everything\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003eThe server only ever acts on the exact paths you selected and confirmed in the GUI. Nothing is automatic.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003e🔒 Scan-gated deletion\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003eIt refuses to remove any path that didn't come from a scan result — the GUI cannot ask it to touch arbitrary files.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003e⛔ Protected areas\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003e\u003ccode\u003e/System\u003c/code\u003e, \u003ccode\u003e/usr\u003c/code\u003e, \u003ccode\u003e/bin\u003c/code\u003e, your home root, and more are hard-blocked, then re-checked on disk right before any deletion (TOCTOU-safe).\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003e🧩 Zero runtime dependencies\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003eBackend is pure Node.js built-ins (\u003ccode\u003ehttp\u003c/code\u003e, \u003ccode\u003efs\u003c/code\u003e, \u003ccode\u003echild_process\u003c/code\u003e). The whole thing is small enough to audit yourself.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003e🏠 Local only\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003eBinds to \u003ccode\u003e127.0.0.1\u003c/code\u003e with a per-session token. No telemetry, no network calls, nothing leaves your Mac.\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 📦 Install\n\nRequires **Node.js 18+** and **macOS**.\n\n```bash\ngit clone https://github.com/vstorm-co/mac-clean.git \u0026\u0026 cd mac-clean\nnpm install\nnpm run build\nnpm link          # makes the `mac-clean` command available globally\n```\n\n\u003e Prefer not to link? Just run `npm start`.\n\n---\n\n## 🚀 Usage\n\n```bash\nmac-clean              # starts the local server and opens the GUI in your browser\nmac-clean --port 5000  # use a different port\nmac-clean --no-open    # don't auto-open the browser; the URL is printed instead\n```\n\nmac-clean opens, scans your whole Mac in the background, and streams results in as\nthey're found. Then:\n\n| | Step |\n|:-:|------|\n| 1 | **Storage overview** — see your disk, biggest home folders, and largest apps at a glance. |\n| 2 | **Review** — categories are colour-coded by risk (🟢 safe · 🟡 moderate · 🔴 risky) and sorted by size. Click a category to expand its files. |\n| 3 | **Select** — click any file row to tick it. Use **Reveal** to open it in Finder first. |\n| 4 | **Approve** — *Move to Trash* (recoverable) or *Delete permanently…* (double-confirmed). |\n\n---\n\n## 🗂️ Categories\n\n| Category | Risk | What it finds |\n| --- | --- | --- |\n| Trash | 🟢 safe | Items already in the macOS Trash |\n| Temporary files | 🟢 safe | Leftovers in `/tmp` |\n| Browser caches | 🟢 safe | Chrome / Safari / Firefox / Arc / Brave / Edge caches |\n| Homebrew cache | 🟢 safe | Downloaded installers / old versions (`brew --cache`) |\n| Docker* | 🟢 safe | Unused images, containers, build cache (`docker system df`) |\n| Application caches | 🟡 moderate | Per-app caches in `~/Library/Caches` |\n| Logs | 🟡 moderate | `~/Library/Logs` |\n| Developer caches | 🟡 moderate | npm, Yarn, pnpm, pip, CocoaPods, Gradle, Cargo, Xcode |\n| node_modules folders | 🟡 moderate | Dependency folders in your project directories |\n| Orphaned launch agents | 🟡 moderate | `~/Library/LaunchAgents` entries pointing to missing programs |\n| Old downloads | 🔴 risky | `~/Downloads` items untouched for N days |\n| Large files | 🔴 risky | Big files in Downloads / Documents / Desktop |\n| Large folders | 🔴 risky | Every folder over a size threshold (VMs, AI models, app data, projects) |\n| Applications | 🔴 risky | Installed apps you can move to the Trash |\n| iOS device backups | 🔴 risky | iPhone/iPad backups stored on this Mac |\n| Mail attachments | 🔴 risky | Attachments cached by Mail.app |\n| Duplicate files | 🔴 risky | Identical files (SHA-256), nothing pre-selected |\n\n\u003e \\* **Docker** lives inside its own virtual disk, so it can't be trashed file-by-file.\n\u003e mac-clean reports what's reclaimable and gives you a **Copy** button for the\n\u003e `docker system prune -af` command to run yourself — it never runs it for you, and\n\u003e that one is **not** recoverable from the Trash.\n\n---\n\n## ⚙️ How it works\n\nA tiny local HTTP server (pure Node) does the scanning and serves a plain\nHTML/CSS/JS GUI you open in your browser. Sizes are computed with the system `du`\nand `find` tools across parallel workers, so a full scan of every category finishes\nin a few seconds.\n\n```\nsrc/\n  cli.ts            entry point: start server, open browser\n  server.ts         HTTP server, scan (SSE) + delete endpoints\n  security.ts       protected-path rules and deletion validation\n  trash.ts          move-to-Trash / permanent delete\n  du.ts · fsfind.ts fast, read-only size + file discovery\n  scanners/         one module per group of categories\npublic/             the GUI (plain HTML/CSS/JS)\nscripts/            trash-items.js (native trashing via osascript)\n```\n\n```bash\nnpm run typecheck   # type-check without emitting\nnpm run build       # compile to dist/\n```\n\n### Full Disk Access\n\nmacOS protects some locations (parts of `~/Library`, the Trash, …). If a scan looks\nincomplete, grant your terminal **Full Disk Access** in\n*System Settings → Privacy \u0026 Security → Full Disk Access*. Moving items to the Trash\nworks without it.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n\u003cp align=\"center\"\u003e\u003csub\u003eScan · review · you approve every deletion.\u003c/sub\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvstorm-co%2Fmac-clean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvstorm-co%2Fmac-clean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvstorm-co%2Fmac-clean/lists"}