disk-tool

Cross-platform local web disk usage analyzer (TreeSize-inspired). Overview first, drill down on demand — no full-tree scan upfront.

Product goal

Guide users to where disk space is consumed, surface actionable cleanup candidates, and produce support-ready reports.

User need	disk-tool response
"What's eating my disk?"	Overview % breakdown → drill into heavy folders
"Leftover dev junk?"	Detects node_modules, .venv, target/, caches
"Old installers in Downloads?"	Flags large .exe, .zip, .msi, etc.
"Docker filling the disk?"	Docker reclaim preset — confirmed docker system prune (volumes kept)
"Need a ticket for IT/support?"	Copy report or export Support ticket (plain text)

Insights improve as you drill — scan Users or Projects to uncover nested node_modules and caches.

Safe cleanup guide

Zone	Meaning	Delete via disk-tool?
review	Regenerable dev artifacts (node_modules, target/)	Yes, after review
maintenance	User temp folders	Yes, with age filter
caution	Shared caches (.npm, .gradle), Docker data roots	Review carefully; Docker roots are not filesystem-deletable
diagnostic	Crash dumps, minidumps	No — view only
critical_os	Windows, /usr, Program Files	No
forbidden	System32, /proc	Hidden from scan

Also protected: virtual disk / disk-image files (.vhd, .vhdx, .vmdk, etc.) — listed in Largest Files when large, but Delete is disabled and cleanup skips them.

Deletes always confirm: single-file and bulk cleanup use review → dry-run → checkbox + type DELETE (no one-click browser prompt).

Use Maintenance (Insights panel) after a scan — guided OS actions, not just "protected zone" warnings:

Action	What it does
Temp cleanup	Review + delete user temp folders (maintenance zone)
Empty recycle bin	Empties Recycle Bin / Trash (Windows, Linux, macOS) with confirm gate
Docker reclaim	docker system prune -af — reports honest before/after docker system df
Compact WSL / Docker disk	Windows only — shuts down WSL and compacts VHDX to free host disk space
Critical OS	Read-only guidance — use Settings → Storage or cleanmgr, not file delete

Maintenance presets (legacy quick picks) remain below the hub:

• Dev reclaim / Temp cleanup / Downloads sweep — filesystem candidates
• Docker reclaim — see above; on Windows, prune layers inside VHDX without shrinking the file — use Compact WSL afterward

Scan your user profile rather than C:\ or / when cleaning up.

How scanning works

1. Overview — lists top-level folders with accurate total sizes (% of root). Each top-level folder is sized in parallel (no full-tree walk).
2. Drill-down — click a folder or Scan folder deeper to scan 5 levels inside that branch only.
3. Repeat — folders at the depth limit show a + badge; drill again to go deeper.

This avoids loading huge trees into memory and prevents scan deadlocks on large disks.

Live demo

Try a sample scan in your browser (no install): jcuel.github.io/disk-tool/demo/

Product overview: jcuel.github.io/disk-tool/

Download

Pre-built artifacts are on the Releases page.

What you want	Windows	Linux	macOS
Desktop app (double-click)	*_x64-setup.exe (NSIS) or .msi	.AppImage or .deb	.dmg
CLI (terminal / scripts)	disk-tool-windows-amd64.exe	disk-tool-linux-amd64	disk-tool-darwin-*

Do not double-click disk-tool-windows-amd64.exe expecting the desktop UI — that file is the CLI build. It now starts disk-tool serve (browser + console) when launched with no args, but the desktop installer is the recommended experience.

Desktop app: install from the NSIS/MSI (Windows), AppImage/deb (Linux), or dmg (macOS) on Releases.

CLI: download the platform binary and run from a terminal:

disk-tool serve          # Linux/macOS
disk-tool.exe serve      # Windows
disk-tool scan C:\Users --json

Windows Defender / SmartScreen: unsigned installers may trigger a false positive. Builds are ClamAV-scanned in CI before release. See SECURITY.md.

The desktop app runs the same Go server as disk-tool serve --no-open in a native window — no separate browser tab.

Desktop development

Requires Rust stable, Node.js 22+, Go 1.25+, and platform Tauri dependencies (Linux deps).

# Linux / macOS — full desktop build (web → embed → Go sidecar → Tauri bundle)
make desktop

# Sidecar smoke only
make smoke-sidecar

# Windows
./build.ps1 -Desktop

Layout: desktop/ (Tauri shell) bundles bin/disk-tool as an externalBin sidecar. The UI is embedded in Go only — Tauri navigates the webview to http://127.0.0.1:<port> after the sidecar emits disk-tool-ready port=N.

Quick start

# Build (requires Node.js + Go)
cd web; npm ci; npm run build; cd ..
Copy-Item -Recurse -Force web\dist\* cmd\disk-tool\static\
go build -o bin/disk-tool ./cmd/disk-tool

# Web UI (opens browser)
./bin/disk-tool serve

# Headless overview (top-level only)
./bin/disk-tool scan C:\Users --json

# Full tree (legacy, use for small paths only)
./bin/disk-tool scan . --full --json

On Linux/macOS use make build if Make is available.

Commands

Command	Description
disk-tool serve [--port 8080] [--no-open] [--ready-stdout]	Local web UI on 127.0.0.1 (--port 0 = OS-assigned; --ready-stdout for desktop sidecar)
disk-tool scan <path> [--json]	Scan without UI
disk-tool version	Print version

API (localhost)

Method	Path	Description
GET	/api/roots	Common scan roots
GET	/api/disk?path=...	Volume capacity, used, and free bytes
POST	/api/scans	Start scan { "root": "..." }
GET	/api/scans/{id}	Scan status and tree
DELETE	/api/scans/{id}	Cancel overview scan
POST	/api/scans/{id}/expand	Drill into folder { "path": "...", "depth": 5 }
WS	/api/scans/{id}/events	Progress + expand events
GET	/api/scans/{id}/export?format=json|html|ticket|cleanup-json|cleanup-html|cleanup-ticket	Export scan or cleanup report
POST	/api/scans/{id}/open	Open path in OS file manager { "path": "..." }
POST	/api/scans/{id}/delete	Delete path under scan root { "path": "...", "confirm": true, "confirmPhrase": "DELETE" }
POST	/api/scans/{id}/cleanup	Bulk cleanup dry-run or execute { "paths": [...], "dryRun": true, "confirm": false, "confirmPhrase": "" }
GET	/api/scans/{id}/maintenance-presets	Maintenance preset definitions + matched paths
GET	/api/scans/{id}/docker	Docker CLI status + system df summary (or unavailable)
POST	/api/scans/{id}/docker/prune	Docker prune dry-run or execute { "dryRun": true } / { "dryRun": false, "confirm": true, "confirmPhrase": "DELETE" } (no --volumes; response includes beforeReclaimable, afterReclaimable, noChange)
GET	/api/maintenance/recycle	Recycle bin / trash size (cross-platform)
POST	/api/maintenance/recycle/empty	Empty recycle bin { "dryRun": true } or execute with confirm + DELETE
GET	/api/wsl/disks	List compactable WSL/Docker VHDX files (Windows)
POST	/api/wsl/compact	Compact VHDX { "path": "...", "dryRun": true } or execute with confirm + DELETE

CI and smoke tests

Pipeline: .github/workflows/ci.yml

Job	Environment	Checks
test-linux	ubuntu-latest	go test, govulncheck, build, API smoke, sidecar smoke
desktop-check	ubuntu-latest	cargo check for Tauri shell + sidecar install
test-windows	windows-latest	build.ps1, govulncheck, scripts/smoke-api.ps1
docker-smoke	ubuntu + Docker	CLI scan + in-container API smoke
e2e-linux	ubuntu-latest	scripts/e2e-run.sh — Cypress browser tests
security	Trivy	Filesystem + container image (CRITICAL/HIGH); PR comment with scan tables
clamav	ClamAV	Malware scan on Linux + Windows cross-compiled binaries
sync	ubuntu-latest	Project board sync after merge (sync-project-board.yml)

Local smoke

# Windows
.\build.ps1
.\scripts\smoke-api.ps1

# Linux / WSL / macOS
make build
make smoke-api
bash scripts/smoke-docker.sh   # requires Docker

# Cypress E2E (Linux/WSL — builds server + runs headless browser tests)
bash scripts/e2e-run.sh

On pull requests, CI uploads E2E screenshots as artifacts and posts a sticky PR comment with inline UI snapshots (artifact link fallback when inline upload is unavailable).

# Windows E2E (after ./build.ps1)
.\scripts\e2e-run.ps1

Docker

docker compose build
docker compose run --rm smoke          # CLI JSON scan
docker compose run --rm smoke-api      # API smoke in Alpine

In-app Docker reclaim (Maintenance hub or docker-reclaim preset) requires the docker CLI on PATH and a running daemon. It runs docker system prune -af (volumes are never pruned) and reports reclaimed bytes from before/after docker system df only — if Docker reports no change, the UI warns that host disk may not shrink on Windows until WSL/VHDX compact. Docker data roots and VHDX files are never filesystem-deleted.

Development workflow (SPECBOOT)

Command	Stage
/enrich-us	Refine user story
/propose	Create proposal artifacts
/apply	Implement on a feature branch
/verify	Run tests and validation
/code-review	Review against spec
/archive	Merge spec deltas
/commit	Git commit (with approval)

OpenSpec layout: openspec/. Slash commands: .cursor/commands/.

Tracking: Issues · Project board · Milestones. See .github/PROJECT.md for status, comments, and views.

Community

Document	Purpose
CONTRIBUTING.md	Fork → dev workflow, tests, PR expectations
Issue templates	Bug, OpenSpec change, chore, question
CODE_OF_CONDUCT.md	Community standards
SECURITY.md	Vulnerability reporting
LICENSE	PolyForm Noncommercial — collaborate freely; commercial use requires permission

Contributors open PRs against dev. Only the maintainer merges dev → master for releases.