unidirstat

Universal cross-platform disk usage visualizer — one CLI for every OS.

npx unidirstat auto-detects your platform and launches the native experience:

• Windows → WinDirStat
• macOS → MacDirStat
• Linux → LinDirStat

Same UI, same features, OS-native backends. Inspired by WinDirStat, rebuilt for the modern stack.

Quick Start

npx unidirstat
npx unidirstat ~/Documents
npx unidirstat / --port 5173 --no-open
# also aliased as dirstat
npx unidirstat --help

Or install globally:

npm i -g unidirstat
unidirstat ~/Downloads

The CLI starts a local Node backend on a random port, scans the target, and opens the browser UI automatically (http://localhost:<port>).

What You Get

Frontend (shared web UI, ported from the macdirstat demo):

• Native window chrome (traffic lights, titlebar, menubar, toolbar)
• Tree view with Size Proportion bars, %, Physical/Logical Size, Files — expandable, selectable, synced with treemap
• Extension legend (.dmg, .mp4, .zip, .app, …) with color swatches
• Treemap with glossy tiles, hover labels, selection sync — squarified layout scaled by size
• Status bar with selection, size, file count, memory
• Progress bar + Scan Again / Rescan

Backend (Node launcher + OS adapters):

• Windows: NTFS/ReFS scan, Reveal in Explorer, Delete / Recycle Bin
• macOS: APFS/HFS+ scan, Reveal in Finder, Move to Trash, Quick Look, mount awareness
• Linux: ext4/btrfs/xfs, reveal in file manager, trash/delete

All Menus Are Functional

• File: Open directory/drive, Rescan current, Export report (JSON), Save snapshot, Quit
• Edit: Copy path, Copy selected info, Select all / Deselect
• Clean Up: Reveal in file manager, Move to Trash / Recycle Bin, Delete permanently
• View: Toggle columns, Color mode, Toggle treemap, Dark/light, Sort (name/size/files)
• Tools: Largest files, Duplicate hint, Filter by extension, Ignore patterns, Volume info, Open terminal at folder
• Options: Exclusions (e.g. node_modules), Symlink handling, Hidden files, Performance limits
• Help: Keyboard shortcuts, Version, Issue reporting, About

Architecture

unidirstat (CLI: bin/dirstat.js)
  ├─ detects process.platform → Win/Mac/LinDirStat branding
  ├─ starts server.js (HTTP + scan + actions) on free port
  ├─ opens browser to http://localhost:<port>
  └─ serves public/index.html + public/app.js (treemap/tree/legend)

server.js
  ├─ scanDir(root, opts) → recursive fs.readdir/stat, size aggregation
  ├─ adapters/os.js → reveal/trash/delete per platform
  └─ HTTP API:
     GET  /api/health
     GET  /api/scan?path=/some/dir
     POST /api/action {action, path}

Stack: Node.js + vanilla HTML/CSS/JS + Canvas treemap. Future: Rust scanner core for 10× speed.

CLI Options

Usage:
  npx unidirstat [path] [options]

Options:
  --help, -h       Show help
  --version, -v    Show version
  --port <n>       Port (default: 0 = random free port)
  --no-open        Don't auto-open browser
  --host <host>    Host (default: 127.0.0.1)

Development

git clone https://github.com/dirstat/dirstat.git
cd dirstat
npm install
node bin/dirstat.js ~/Documents

License

MIT — new inspired logo recommended (don’t reuse exact WinDirStat logo verbatim).