A next-generation storage mapping engine — visualize, analyze, and reclaim digital real estate with surgical precision. No registry scars. No data residue. Just clean, actionable insight.

• The Big Picture – Why FolderSizes Exists
• Core Architecture (Mermaid Diagram)
• Feature Constellation
• Compatibility Galaxy – OS Matrix
• Getting Started – Console Invocation
• Profile Configuration – Example
• API Ecosystem – OpenAI & Claude Integration
• Responsive UI & Multilingual Support
• 24/7 Customer Support Philosophy
• License & Legal Framework
• Disclaimer of Intent

Imagine your hard drive as a sprawling library where every book is a file, every shelf a folder—but no one has cataloged the place in years. FolderSizes is the librarian with X-ray vision. It doesn't just count gigabytes; it reveals the story behind the storage: orphaned temp data, duplicate media collections, forgotten node_modules graveyards, and the silent creep of log files.

This is not a "cleaner." This is a spatial intelligence compass for your digital terrain. Whether you're a system architect managing petabyte-scale arrays or a photographer whose Lightroom catalog has grown teeth, FolderSizes provides the cartography you never knew you needed.

Why the alternative approach? Traditional tools either hide behind paid walls or leave registry trails that compromise system integrity. FolderSizes delivers deep scanning via a modular, sandboxed engine that respects your machine's sovereignty. The scanning payload is a single binary—no sidecars, no telemetry, no background services.

The engine is built around a four-tier pipeline: Discovery → Aggregation → Rendering → Export. Each stage is independently replaceable. The diagram below illustrates how a raw filesystem snapshot transforms into actionable heatmaps.

graph TB
    subgraph Tier_1_Discovery
        A[Filesystem Walker] --> B[Metadata Extractor]
        B --> C[Duplicate Analyzer]
    end

    subgraph Tier_2_Aggregation
        C --> D[Volume Mapper]
        D --> E[Compression Engine]
        E --> F[Cache Layer]
    end

    subgraph Tier_3_Rendering
        F --> G[SVG Treemap Generator]
        F --> H[Sunburst Diagram Engine]
        F --> I[Table View]
    end

    subgraph Tier_4_Export
        G --> J[CSV / JSON Exporter]
        H --> J
        I --> J
        J --> K[Portal Connector]
    end

    K --> L[[OpenAI / Claude Schema]]
    D --> M[Threshold Alarm System]
    M --> N[Notification Webhook]

Pipeline philosophy: Every block is swappable. Don't like the treemap renderer? Write your own and plug it in. The API contract is just two endpoints: IngestScan and EmitReport.

Special note for macOS Sequoia (15): We've pre-authorized the scanning kernel extension. Gatekeeper will not block the initial scan path.

FolderShips with a unified binary. No installers. No dependency surgeries. Below is a representative invocation that scans a mounted volume, outputs a treemap, and pings a Slack webhook if any single folder exceeds 50 GB.

foldersizes --scan /mnt/data --output-format svg --alarm-threshold 50GB \
  --webhook https://hooks.slack.com/services/YOUR_WEBHOOK \
  --export-path ~/reports/volumescan_$(date +%Y%m%d_%H%M%S).svg

Expected output:

[INFO] Scanning volume: /mnt/data (4.2 TB total)
[INFO] Discovering 1,847,329 files across 42,188 folders
[INFO] Pattern analysis: 203 GB of log files detected
[WARN] Folder "archived_backups_2024" exceeds 50 GB threshold (67.3 GB)
[INFO] SVG treemap written to ~/reports/volumescan_20261215_143052.svg
[INFO] Webhook delivered with threshold alert

The binary is self-contained—no PATH modifications required. Place it in a directory of your choosing and invoke by full path or alias.

Profiles allow you to save scanning preferences for recurring use. Below is a YAML-based profile for a media production studio.

profile_name: "post_production_scan"
version: 2026.1
author: system_administrator

scan_defaults:
  exclude_paths:
    - "/.Trash"
    - "/.DocumentRevisions"
    - "/.Spotlight-V100"
  include_fs_types:
    - "apfs"
    - "ext4"
    - "ntfs"
  max_depth: 12

alarms:
  - condition: "folder_size > 100GB"
    action: "email_admin"
    cooldown_hours: 24
  - condition: "duplicate_media > 50GB"
    action: "slack_notify"
    cooldown_hours: 6

export:
  format: "csv"
  compression: "zstd"
  destination: "s3://reports-bucket/foldersizes/"

Profiles are loaded with the --profile flag:

foldersizes --profile post_production_scan --scan /Volumes/MediaRaid

FolderSizes ships with a dual-LLM connector that transforms raw scan data into natural-language storage recommendations.

The engine sends a compressed scan summary to OpenAI's API. The model returns:

• A plain-English audit of storage anomalies
• Suggested archival strategies (e.g., "The 180 GB of raw video proxies from March 2024 appear unused. Consider cold storage.")
• Duplicate remediation priorities ranked by risk and gain

Configuration snippet:

ai_connector:
  provider: "openai"
  model: "gpt-4o-2026-01-18"
  temperature: 0.2
  max_tokens: 4000
  system_prompt: "You are a storage efficiency architect..."

Claude receives the same scan payload but operates under a different analytical framework—focusing on hierarchical relationships and long-term data lifecycle. Claude excels at detecting organizational anti-patterns (e.g., nested node_modules that mirror production dependencies).

Configuration snippet:

ai_connector:
  provider: "claude"
  model: "claude-sonnet-4-20260501"
  temperature: 0.1
  max_tokens: 5000
  system_prompt: "Analyze this filesystem tree for lifecycle inefficiencies..."

Why both? Each model brings unique strengths. OpenAI is faster for shallow dives; Claude provides deeper structural insights. You can alternate based on context, or run both in parallel for a consensus view.

The web dashboard (optional, HTTP server started with foldersizes serve) adapts to everything from a 4K monitor to a phone held sideways on the subway.

• Layout: CSS grid with automatic column collapse. On mobile, treemaps become stacked bar charts.
• Localization: 14 languages shipped — English, Spanish, French, German, Japanese, Korean, Simplified Chinese, Traditional Chinese, Portuguese, Russian, Arabic, Hindi, Dutch, and Italian.
• Accessibility: WCAG 2.2 AA compliant. Keyboard-navigable treemaps with ARIA labels for screen readers.

The UI communicates via WebSocket for live scan updates—no page refreshes needed. A 500 GB scan on a mid-range SSD shows progress down to the individual folder level.

We don't use chatbots as shields. Support is human-first, async-second.

• Priority Lane (critical issues): Response within 60 minutes, 24/7. Includes system integrators and enterprise licensees.
• Standard Lane (configuration questions): Response within 4 business hours, regardless of timezone.
• Community Forum: Peer-to-peer troubleshooting with developer presence. Average answer time: 2.3 hours.

Every feature request is triaged weekly. If three or more customers request the same capability, it enters the development pipeline within the next release cycle—no bureaucracy, no product committee.

This project is released under the MIT License. You are free to use, modify, and distribute the software, provided the original copyright notice is preserved.

MIT License

Copyright (c) 2026 FolderSizes Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions...

FolderSizes is a directory analytics tool. It performs read-only filesystem traversals and generates statistical reports. It does not modify, delete, encrypt, or transfer files unless explicitly instructed by the user via an exported script or external integration. The "Get Release" button above provides access to the authorized distribution channel; the software is offered as-is, with no warranty of merchantability or fitness for a particular purpose.

Users are solely responsible for ensuring that their use of this software complies with applicable local, national, and international regulations—including but not limited to data privacy laws (GDPR, CCPA), export controls, and organizational IT policies.

Built for the curious, the meticulous, and the storage-weary.