Coding agents make experiments cheap: parallel worktrees, cloned projects, repeated dependencies, build output, model files, and forgotten prototypes accumulate quickly. ZeroSpace inspects a chosen storage scope, surfaces general clutter, verifies exact duplicates with full-file SHA-256, and explains why an item may be worth reviewing.
Agent-heavy developers are the intended audience, not a restriction on the scan. Every file reached in the selected scope participates in size, age, and exact-duplicate analysis; named categories such as dependencies, models, archives, and caches are highlights rather than an allowlist.
It is an experimental, open-source developer tool, not a consumer Mac cleaner. Scans and paths stay local, nothing is changed automatically, and normal cleanup moves reviewed items to Trash.
ZeroSpace is also meant to be reusable. You can run it as a standalone local app, call the CLI from agent workflows, wire the JSON output into your own scripts, or adapt the MIT-licensed code in your own product.
- Digital Archaeologist: rule-based explanations for repeated dependencies, caches, checkpoints, generated assets, installers, and forgotten experiments.
- Exact duplicate evidence: size and 8 KB header prefilter followed by full-file SHA-256 verification.
- Big File Radar and treemap: inspect large or stale files across the chosen storage scope.
- Finder integration: reveal every candidate before taking action.
- Review-first cleanup: nothing is selected automatically; normal removal moves items to
~/.Trash. - User-controlled policies: local Settings persist compression mode, confidence/savings/size thresholds, excluded extensions and paths, confirmation requirements, archive destination, and optional global-cache analysis. Settings never bypass backend safety gates.
- Local reports: export scan results as JSON or CSV.
- Protection Shield: blocks mutations to macOS system and sensitive user paths.
- Incremental local inventory: completed scans keep a local SQLite inventory in
~/Library/Application Support/ZeroSpace. Scan updates reuses unchanged metadata and verified hashes; Full refresh reconciles every file. The inventory never leaves the Mac and can be cleared per scope in Settings. - Exhaustive, bounded-memory enumeration: every accessible file in the selected scope is counted. Duplicate candidates are indexed in a temporary on-disk SQLite database, while RAM retains only bounded UI samples and top files.
- Real progress and cancellation: the UI reports backend file/folder counts, and cancelling signals the scanner itself to stop—not only the browser request.
ZeroSpace does not use a machine-learning model. Its candidate scores are transparent heuristics for ranking review—not probabilities or guarantees that a file is safe to remove.
ZeroSpace is not trying to replace polished disk visualizers or one-click cleaner apps. Disk visualizers are excellent for seeing where storage went; dedicated cleaner apps are useful for targeted cache cleanup.
ZeroSpace focuses on a narrower workflow:
- local, review-first evidence before deletion;
- agent/developer workspace debris alongside ordinary clutter;
- exact duplicate verification kept separate from recommendations;
- CLI/JSON output for agents, CI, and product integrations;
- MIT-licensed code that other builders can adapt.
ZeroSpace can run headlessly inside an agent workflow without starting the browser:
hd-detective scan .
hd-detective scan . --json > zerospace-report.json
hd-detective scan . --json --fail-on duplicates
hd-detective scan . --full-refreshThe CLI is read-only. Human output is the default; --json emits a versioned schemaVersion: 1 report with a deduplicated findings array containing paths, sizes, categories, confidence, reasons, evidence sources, duplicate groups, and recommended actions. --fail-on findings or --fail-on duplicates returns exit code 1 for CI/agent gating; successful scans return 0, and invalid or failed scans return 2.
This makes ZeroSpace useful as a storage-hygiene layer before an agent opens a pull request or starts another experiment. The localhost REST API remains available for richer integrations. An MCP server is intentionally not bundled; the CLI and JSON contract are the stable integration surface for now.
Copy-paste recipes are in examples/agent-workspace-audit.sh and examples/github-actions-zerospace.yml.
For Codex, Claude, Cursor, or another shell-capable agent, the reusable instruction is simply: “Run hd-detective scan . --json > zerospace-report.json, inspect .findings, and do not delete anything without explicit review.”
ZeroSpace is released under the MIT License so other builders can use it without asking permission. You can:
- embed the scan command in pre-PR, CI, or local agent workflows;
- consume the JSON report in your own dashboards or product checks;
- fork the scanner, UI, or safety rules for a different local-first app;
- redistribute modified versions, provided the MIT license notice is preserved where required.
The project is provided as-is, with no warranty or guarantee that a finding is safe to remove. Treat scan output as review evidence, not an automatic deletion instruction.
To ensure complete transparency as an open-source GitHub project, ZeroSpace v2.0 explicitly documents the following technical scope and system boundaries:
-
Developer distribution: this repository runs a Python localhost service and browser UI. It is not currently a signed or notarized
.app. -
Localhost service: the backend binds only to
127.0.0.1, validates browser origins and Host headers for the selected port, and serves the UI locally. Stop it withCtrl-Cwhen finished. -
Permissions: scan a specific workspace first. Scanning protected locations may require Full Disk Access for Terminal/Python; ZeroSpace does not need it for ordinary project folders.
A completed report identifies how many directories could not be read. A root-volume scan remains on the startup volume and does not descend into separately mounted volumes under
/Volumes. -
Conservative actions: permanent deletion and advanced compression, migration, snapshot, and strategy operations are disabled by default. Review-first mode supports moving confirmed items to Trash.
-
No safety guarantees: duplicate content verification does not prove that a particular path is unused. Always inspect location and context before removal. ZeroSpace is not backup software or a notarized consumer cleaner.
The repository is the supported distribution today. The included Homebrew formula is a development --HEAD formula; stable signed and notarized releases are not currently published.
Clone and run the backend using Python 3. The backend uses only the Python standard library; the UI currently loads fonts and icons from public CDNs.
git clone https://github.com/LinusInnovator/zerospace.git
cd zerospace
# Start the localhost workspace inspector
./launch.shOpen the URL printed by launch.sh (normally http://127.0.0.1:8080; it selects the next free localhost port if needed), choose a project/workspace folder, and scan. Use Ctrl-C in Terminal to stop the service.
hd-optimizer-detective/
├── scanner_backend.py # Multi-threaded Python HTTP Server, sysctl hardware query, Protection Shield, os.walk audit engine
├── index.html # 2026 Bento Grid 2.0 structure & Phosphor Duotone vector icons
├── styles.css # Deep obsidian darkmode design system & backdrop glass utilities
├── app.js # Reactive UI controller, SHA-256 smart selection & modal state managers
├── launch.sh # Auto-launch script with port availability checks
├── ARCHITECTURE.md # Detailed system architecture & API specifications
├── CONTRIBUTING.md # Guidelines for open-source contributors
├── SECURITY.md # Security policy & System Protection Shield rules
├── CHANGELOG.md # Release history
└── Formula/ # Homebrew package formula
- Backend: Native Python
http.server.ThreadingHTTPServer,hashlib,subprocess(sysctl -n hw.memsize). - Frontend: ES6 Vanilla JS, CSS3 Container Queries & Grid 2.0, Phosphor Duotone SVG Iconography.
- Security: Localhost binding (
127.0.0.1), restricted CORS, and strict system path locks (is_safe_file_path).
- 📐 Architecture & API Specs
- 🤝 Contribution Guidelines
- 🛡️ Security Policy & Protection Shield
- 📜 Changelog
Pull requests run Python/API/security checks and a CI-only Playwright browser smoke suite on macOS. To run the same browser checks locally, install Node.js and run:
npm ci
npx playwright install chromium
ZEROSPACE_NO_BROWSER=1 ./launch.sh 8080
# In another terminal:
ZEROSPACE_BASE_URL=http://127.0.0.1:8080 npm run test:browserThe browser harness uses temporary fixture workspaces and never scans or modifies a real personal folder.
Distributed under the MIT License. You may use, modify, redistribute, and adapt the project, including in your own products, subject to the license terms. The software is provided as-is, without warranty. See LICENSE for details.