DirWiz

macOS disk usage analyzer with a Metal cushion treemap, fast filesystem scans, duplicate detection, hardlink analysis, and a scriptable CLI.

What It Does

DirWiz scans a volume or folder and builds a compact file tree using on-disk sizes, not just logical file lengths. The app is built for large local volumes where Finder size calculation is too slow or too shallow.

The main UI combines a WinDirStat-style treemap, a sortable file tree, extension breakdowns, search, duplicate groups, hardlink groups, and space insights. Full Disk Access is detected at launch, with clear guidance when macOS privacy permissions will hide files.

Features

• Fast scanner: Uses bulk filesystem metadata reads, bounded worker pools, compact node storage, and deferred tree materialization for large scans.
• Deferred bundle sizing: App bundles stay as opaque leaves during the first scan so the UI becomes usable sooner. Bundle sizes are resolved in the background and propagated into parent totals.
• Metal cushion treemap: Shows disk usage visually with extension-based color mapping, zoom, selection, and hover details.
• Sortable tree table: Browse folders and files by on-disk size, logical size, item count, modified date, and parent percentage.
• Duplicate finder: Groups candidate files by size and hashes, then verifies byte-for-byte before any cleanup action.
• Hardlink analysis: Finds files that share inode identity and reports extra linked bytes for analysis. These bytes are not the same as reclaimable duplicate space.
• Space insights: Breaks usage into categories, file ages, size distributions, iCloud status, APFS clone checks, and local snapshot information.
• Quick Look and Finder actions: Preview files, reveal them in Finder, copy paths, or move selected items to Trash.
• CLI: dirwiz-cli supports scripted scans, JSON export, duplicate checks, volume info, and benchmark runs.

Build

open Package.swift
swift build -c release
swift test

Build a release app bundle:

./scripts/package-release.sh
open dist/DirWiz.app

The package script creates dist/DirWiz.app and dist/DirWiz-1.0.0-macos.zip.

Run the CLI:

.build/release/dirwiz-cli scan /path/to/scan
.build/release/dirwiz-cli scan /path/to/scan --json --max-depth 3
.build/release/dirwiz-cli duplicates /path/to/scan --min-size 1048576
.build/release/dirwiz-cli benchmark /path/to/scan --iterations 3

Full Disk Access

macOS restricts many user and system folders unless the app has Full Disk Access.

For complete scans:

1. Build the app with ./scripts/package-release.sh.
2. Move dist/DirWiz.app to /Applications/DirWiz.app.
3. Open System Settings.
4. Go to Privacy & Security, then Full Disk Access.
5. Add or enable DirWiz from /Applications.

Use the same installed app bundle after granting permission. Do not grant Full Disk Access to .build/release/DirWiz; SwiftPM rebuilds are raw executables and macOS may treat each rebuilt binary as a different app.

This Mac release script signs with a local Apple signing identity when one is available. If none is installed, it falls back to ad hoc signing. Ad hoc builds can lose Full Disk Access after rebuilds because macOS ties privacy grants to code identity.

Architecture

Sources/
├── DirWizCore/   Scanner, FileTree, duplicate detection, hardlinks, diff, export, analysis
├── DirWizUI/     AppState, SwiftUI views, Metal treemap, Quick Look, navigation
DirWiz/           macOS app target
CLI/              dirwiz-cli target
Tests/            Scanner, tree, duplicate, hardlink, treemap, analysis, and UI-state tests

Scanner Notes

DirWiz stores scan results in a flat array tree with a shared string pool. This keeps parent and child references stable by index and avoids per-node object overhead on large scans.

The app path favors quick first results. It skips inline recursive sizing for bundles, renders the tree, then computes bundle sizes as a bounded background task. The CLI defaults to exact inline bundle sizing unless DIRWIZ_SKIP_BUNDLE_SIZES=1 is set.

Useful scan toggles:

DIRWIZ_SCAN_WORKERS=6
DIRWIZ_DEFER_TREE=0
DIRWIZ_SKIP_BUNDLE_SIZES=1
DIRWIZ_BUNDLE_WORKERS=4

Requirements

• macOS 15 or newer
• Swift 6 toolchain
• Xcode command line tools