quantum-file-cleaner

Quantum-fast disk cleaner with a browser UI. Scan any folder for junk (node_modules, .git, dist, build, .tmp, .bak, logs, OS metadata, crash dumps, partial downloads, large old files). Find duplicates by hash. Copy or move at >1 GB/s with real-time MB/s progress. Pure Node.js — zero external dependencies.

npm install -g quantum-file-cleaner
qfc
# opens http://127.0.0.1:8765/ in your browser

Why?

Tools like CCleaner are heavy, closed-source, and platform-locked. Existing npm cleaners (rimraf, npkill) are single-purpose CLIs. quantum-file-cleaner gives you a fast browser UI + a streaming HTTP API for everything — built on pure Node.js so it installs in seconds with no native compilation, no Python, no Electron.

It's designed around four ideas:

1. No fake progress. Every byte copied is reported from a real read-write loop. If I/O stalls, the counter visibly freezes — that's the truth.
2. Same-volume moves are instant. fs.rename() is used when source and destination share a volume — a 100 GB folder moves in milliseconds.
3. Big buffers, real parallelism. 4 MB chunk reads (vs. Node's default ~64 KB), bounded-concurrency worker pool.
4. Safety first. Refuses to touch C:\Windows\System32, /etc, /usr/bin, and other system roots. Refuses to copy a folder into itself. Auto-renames name collisions at destination.

Install

Globally (recommended)

npm install -g quantum-file-cleaner

Then run qfc from any directory.

One-shot via npx

npx quantum-file-cleaner

Locally (in a project)

npm install quantum-file-cleaner --save-dev
npx qfc

Usage

CLI

qfc [options]

Options:
  -p, --port <n>      HTTP port to listen on (default: 8765)
      --host <addr>   Bind address              (default: 127.0.0.1)
      --no-open       Do not auto-open browser
  -h, --help          Show this help
  -v, --version       Show version

Browser UI

After qfc starts, your default browser opens http://127.0.0.1:8765/. Type any folder path and click Scan Folder.

Features in the UI:

• Files tab — every file in the scanned tree, grouped by folder, sortable by size/name/type, filterable by VIDEO/ARCHIVE/EXE/DOCS/OTHER + minimum size.
• Junk Folders tab — every detected dev-artifact folder (node_modules, .git, dist, build, etc.) with auto-calculated total size.
• Multi-select + bulk Delete / Move / Copy with confirmation modal and live progress (bytes copied, MB/s, ETA, current file).

HTTP API

Once qfc is running, you can hit the API directly from any tool. Bodies are JSON; streaming endpoints return NDJSON (one JSON object per line).

| Endpoint | Method | Response | Purpose | |------------------------------------------|--------|-----------|---------| | /api/ping | GET | JSON | Health + features + version | | /api/scan | POST | NDJSON | Single-walk scan | | /api/quantum-scan | POST | NDJSON | Parallel scan + junk-file detection | | /api/calc-size | POST | JSON | Total size + file count of a folder | | /api/find-duplicates | POST | JSON | Hash-based duplicate finder | | /api/quantum-delete | POST | JSON | Parallel deletion | | /api/quantum-copy-stream | POST | NDJSON | Streaming copy with real-time progress | | /api/quantum-move-stream | POST | NDJSON | Atomic move if same volume, else copy+delete |

Example — find duplicates

curl -s -X POST http://127.0.0.1:8765/api/find-duplicates \
  -H 'Content-Type: application/json' \
  -d '{"path":"C:\\Users\\me\\Downloads","min_size_kb":1000}' | jq

Example — streaming copy with progress

curl -X POST http://127.0.0.1:8765/api/quantum-copy-stream \
  -H 'Content-Type: application/json' \
  -d '{"paths":["/home/me/big-folder"],"destination":"/mnt/usb","workers":8"}'

Each line of the response is a progress event:

{"kind":"start","total_files":1234,"total_bytes":52428800000,"destination":"/mnt/usb","atomic_moves":0}
{"kind":"progress","bytes_copied":1048576000,"total_bytes":52428800000,"files_done":24,"total_files":1234,"mbps":520.3,"eta_sec":98,"elapsed_sec":2.0,"current":"video01.mp4"}
{"kind":"file_done","src":"...","dst":"...","size":42000000,"ok":true}
{"kind":"done","ok":1234,"fail":0,"total_bytes":52428800000,"elapsed_sec":100.4,"avg_mbps":498.2}

What it detects

Junk folders (30+ patterns)

node_modules · bower_components · vendor · packages · venv · .venv · .tox · bin · obj · dist · build · out · output · target · .angular · .next · .nuxt · .svelte-kit · .terraform · .serverless · .gradle · __pycache__ · .cache · coverage · .nyc_output · .git · .svn · .hg · .idea · .vs · .vscode

Junk files

| Category | Patterns | |------------|----------| | TEMP | *.tmp, *.temp, *.bak, *.old, *.orig, *.swp, *.swo, ~$*, .~* | | LOG | *.log, *.log.1, npm-debug.log*, yarn-error.log | | OS | Thumbs.db, desktop.ini, .DS_Store | | COMPILED | *.pyc, *.pyo, *.class, *.o, *.obj | | CRASH | *.dmp, Minidump*.dmp | | INSTALL | *.msi.* leftovers | | TEMP/DL | *.partial, *.crdownload, *.download | | EMPTY | 0-byte files (opt-in via flag_empty) | | OLD | >100 MB AND unused 90+ days (opt-in via flag_large_old) |

Safety guarantees

The cleaner refuses any operation that touches these paths:

Windows: C:\Windows\System32, C:\Windows\SysWOW64, C:\Windows\WinSxS, C:\Windows\boot, C:\Windows\Fonts

macOS / Linux: /etc, /bin, /sbin, /usr/bin, /usr/sbin, /lib, /lib64, /boot, /proc, /sys, /dev, /System, /Library/System, /private/etc, /private/var/db

Protected basenames (never deleted regardless of path): pagefile.sys, hiberfil.sys, swapfile.sys, ntuser.dat, system.dat, user.dat, system.ini, win.ini, boot.ini, bootmgr, BOOTNXT, .bashrc, .profile, .zshrc.

Copy/move into self is detected and refused (would cause infinite recursion). Name collisions at destination are auto-renamed with (1), (2), etc.

Performance

Numbers from a developer laptop (NVMe SSD, Windows 11):

| Operation | Result | |-----------|--------| | 500 MB single file copy | 1,199 MB/s avg (peak 1,589 MB/s), 4 progress events | | 1 GB / 5 files parallel copy | 1,498 MB/s avg in 0.7 s | | Same-volume folder move (any size) | <20 ms (uses fs.rename) | | Scan ~10 k files w/ junk detection | <1 s | | Find duplicates among 5 GB | seconds (size-grouped pre-filter) |

Numbers vary by disk speed, file-size distribution, and OS cache state.

Roadmap

• [ ] Recursive scan progress — emit per-subtree events for very large trees
• [ ] Resume support — interrupted copies pick up where they stopped
• [ ] Dry-run mode — preview what would be deleted/moved without doing it
• [ ] Configurable junk patterns via .qfc.json
• [ ] CLI shortcuts — qfc scan ~/Downloads, qfc dupes ~/Pictures, etc. without the UI
• [ ] Trash integration — move to OS trash instead of permanent delete (opt-in)

Contributing

Issues + PRs welcome. The codebase is intentionally small (~1500 lines, zero dependencies). Each lib/*.js module is independently testable.

git clone https://github.com/amasen86/quantum-file-cleaner.git
cd quantum-file-cleaner
node bin/qfc.js
# Edit, hit Ctrl+C, run again

License

MIT — free for personal and commercial use. Attribution appreciated.

Acknowledgements

Built with MYTHOS doctrine in mind: loop reasoning, no fake progress, holistic signals, negative constraints over positive exhortations. Inspired by rimraf (single-purpose perfection), npkill (visual feedback for cleaning), and CCleaner (one place for everything).