TreeMap-Disk-Visualizer

Prithvi-WebMIT活跃维护

跨平台桌面应用,用矩形树图把磁盘占用可视化,方便快速定位大文件并直接删除或打开。

TreeMap is a fully downloadable app that can run on mac, windows, and linux. That visualizeses all of your disk-space into charts and square board. It also lets you delete unwanted files and opens files for you aswell.

v5.2.0发布于 2026-10-26 02:24 UTC1,299star +3 / 7 天92fork同步于 2026-11-10 05:55 UTC

怎么上手

从 README 代码块原样提取,可能是其中一种安装方式
npm install && npm run compile
npx @vscode/vsce package --no-dependencies   # produces a .vsix you can install
npm install
npm run build
npm start
npm install
npm run app          # build + launch the desktop app locally
npm run dist:mac     # produce a macOS .dmg in release/
硬件要求按 README 关键词推断
支持 Apple Silicon
下载:源码 zip·GitHub Releases(安装包)本站不镜像安装包

项目说明

这个项目的说明还在生成中,先参考下面「最近发版」和 README。

最近发版

5 个版本v5.2.0
  1. v5.2.0最新正式版2026-10-26 · 2026-10-26 02:24 UTC

    TreeMap 5.2.0

    A scan engine of its own, safer deleting, and a map you can read at a glance.

    TreeMap now scans with its own engine, written in Rust, and no longer reads the whole disk a second time after every scan, which was the biggest cause of slow, stuttering whole-disk scans. Opening TreeMap never starts a scan by itself, every route to the Trash is more careful, and sizes now use decimal units, as Finder does. It also fixes several security problems, so please update (see Security below). There is no 5.1.0: this release follows 5.0.1.

    ✨ Highlights

    • A native scan engine, written in Rust. It asks the system for a whole folder's list in one request and works on several cores at once. On a Mac, on a 200,000-item folder the computer had read recently, it went through 412,291 items a second against the built-in walker's 131,203: about three times as fast. On a 1,000,000-item folder too big for the file cache, the disk sets the pace: 91,308 items a second, about 11% faster than the walker's 82,497 and slower than the gdu helper 5.0.1 used on a Mac. TreeMap picks the engine for you and says which one ran and why.
    • No more second pass over the whole disk. TreeMap no longer reads the whole disk a second time after every scan. In 5.0.1 that second pass took about half an hour on a test Mac with 9.46 million items, with the app unresponsive for up to 111 seconds at a time.
    • You decide how hard a scan works. A new Scanning budget in Settings: Eco holds a scan to about a quarter of the computer, Balanced to about half and Turbo to nine-tenths. On Automatic, a scan you start runs at Turbo when the computer is plugged in, Balanced on battery and, on a Mac or Linux, Eco when it runs hot. On Automatic, scheduled scans and Autopilot never go above Balanced, and while one of them runs, your scan runs one step lower.
    • Safer deleting with the Undo Vault. The Time Capsule is now the Undo Vault. The Clean Up cart and Autopilot never send an item to the Trash without a whole, checked copy: an item that cannot fit is left in place and named, and each item is checked again right before it goes. Undo now puts back permissions as well as dates, and it names anything it could not put back. Copies are kept 30 days by default, or less to stay under the size cap.
    • A map you can read at a glance. Tiles keep their full colour at every depth. Every outline stands out at a contrast of 3:1 or better in both themes, and each label is black or white, whichever reads better, at 4.5:1 or better. A key under the map names the markings on screen, lines stay sharp at 125, 150 and 175% display scaling, and a click opens one folder at a time.
    • Clean Up asks first and says what a move to the Trash does. Move to Trash no longer deletes on one click: it opens the same "Move to Trash?" dialog as every other view. Online-only files are no longer called safe to remove, since moving one to the Trash deletes it from the cloud too. Empty folders never offers a folder the scan could not see into, and Clean Up now says the space comes back only when you empty the Trash. The Autopilot policy editor, which could not be used in 5.0.1, now works.
    • You choose what to scan. A start screen offers your last folder first, then Desktop, Documents, Downloads, your home folder and the whole drive. After a Stop, the same scan is one click away.
    • More guard rails. A scan stays on the drive it starts on unless you ask otherwise. Every Trash sheet warns before you trash part of an installed app, every offload lists what it will move and asks first, and an offload that would free nothing is refused.
    • Better with a keyboard and a screen reader. Screen readers hear what each view is working on, the notes that appear, and a scan's progress from any view. Every confirmation opens on a safe control and names what it will do, Shift+F10 opens the focused item's menu, and focus is handed back, not dropped to the top of the page, when
  2. v5.0.1v5.0.1 Minor Bug Fixes2026-09-08 · 2026-09-08 04:53 UTC
    查看更新说明

    TreeMap 5.0.1

    Every bug reported against 5.0.0 is fixed in this release; the four reports are linked below. Numbers and dates now read the English way on every machine, and the Windows pages say Windows things.

    Changed

    • The mouse pointer inside TreeMap is now TreeMap's own. Instead of the system arrow, hand and I-beam you see one small dot, drawn eight ways: plain, over something clickable, in a text field, ready to grab, dragging, crosshair, resizing and disabled. It is pale on the dark theme and ink-dark on the light one, and each shape has a thin edge in the opposite shade so it stays visible on a treemap tile of its own colour.
    • The dot is a true system cursor, so it moves exactly with your hand, never lags, and never disappears while TreeMap is busy. Every hover effect is unchanged: the dot tells you what kind of thing is under it, and the control's own highlight still tells you which one.

    Fixed

    • A release could lose its installers, with no way to get them back. On GitHub the download files belong to the release page, not to the version number, so when the v5.0.0 page was deleted and made again it came back with nothing to download (#32). Two things changed. A new release is published only after both installers are attached and checked, one by one, by name and size, so a release with an empty download list is no longer possible. And a release that has lost its files can have them rebuilt and put back (Actions → Build & Release → Run workflow → type the tag). What you will see: every release page lists the macOS and Windows installers.
    • Windows restore points are measured in every language, and without guessing. The Missing GB receipt and the Dashboard now ask Windows for the space its restore points use as plain numbers. Before, TreeMap read the text Windows prints on screen (vssadmin) and looked for English labels in it; on a Portuguese Windows that text reads "Espaço de armazenamento de cópias de sombra usado: 7,98 GB", so nothing was found and the receipt showed nothing (#33). The receipt for one drive no longer counts another drive's restore points; when Windows cannot say which drive a restore point belongs to, the receipt says the figure covers the whole PC. Windows normally shows that space only to an administrator. When it is withheld, the receipt says so and tells you how to see it: quit TreeMap from its icon in the system tray, then start it with Run as administrator. The tray step matters: if a copy is still running there, the administrator copy closes at once and you would think nothing happened.
    • Windows and Linux are no longer told about the Mac in the Dashboard, the Missing GB receipt, the preview pane and the first-run card. On Windows, TreeMap used to talk about Time Machine, Full Disk Access and "This Mac". Every one of those sentences now names your own system: restore points and running as an administrator on Windows, "This PC", and plain words like "this computer" until TreeMap knows which system it is on. The receipt's example of a file that reserves more room than it fills is now a Windows one (WSL's ext4.vhdx) rather than Docker.raw, and the hint for installing the video re-encoder names the Windows tool (winget) instead of the Mac one (Homebrew). This is the other half of the #33 report.
    • Numbers and dates are written the English way on every machine. On a Portuguese or German computer TreeMap printed "1.234 shapes" beside "1.2 GB", the same dot meaning thousands in one number and tenths in the other. On an Arabic computer it printed Arabic-Indic digits inside English sentences. Counts had followed the computer's regional settings while sizes always used an English
  3. v5.0.0v5.0.0 Disk City2026-09-03 · 2026-09-03 06:48 UTC
    查看更新说明

    TreeMap 5.0.0

    The first public release since 3.2.1. Everything below landed in the seven months of work between them — the whole 4.x line was developed in the open repository but never published, so this is the release where all of it arrives at once.

    If you are upgrading from 3.2.1, the short version: TreeMap now tells you what is safe to delete rather than only what is big, it can account for every gigabyte on the volume rather than only the ones it walked, and the numbers it prints have been audited against the code that produces them.

    Added

    Deciding what to delete

    • Reclaim Score. Every file and folder gets a score out of 100 for how safe and how worthwhile it is to remove, built from six signals: size against this scan's own spread, how long since it was last opened, whether a rule says it rebuilds itself, whether an identical copy is on this disk, whether it was downloaded, and whether a copy exists elsewhere.
    • A badge beside each score opens a breakdown that says what every signal contributed and, in amber, what could not be measured. A signal TreeMap cannot read is named and left out — never counted as zero.
    • A treemap colour mode and a sort that answer "what is safest to delete" instead of "what is biggest".
    • The six weights are yours to change in Settings, with a reset. Setting one to zero removes that signal rather than scoring it worthless.
    • A radar chart shows all six signals as one shape, so two files compare by silhouette. A signal that could not be measured keeps its spoke and the outline breaks around it.
    • Last-opened dates, with the source that answered them named — and an honest "not available here" where the operating system does not record them, never a stand-in date.
    • "Does a copy of this exist elsewhere?" — a recoverability verdict from Git, backups and cloud sync, with its reasons. It is never promoted to a definite yes by inference: a folder that is merely absent from a backup exclusion list is unknown, not backed up.

    Searching

    • A search grammar: size>100mb ext:mp4, -in:node_modules, modified>90d, used>1y, git:pushed, score>70.
    • A live query box with autocomplete, and saved views you can pin as chips.
    • Ask in plain words. The ✨ button turns "big videos I haven't opened in a year" into a real query, and always shows you the translation in an editable field before it runs. It works entirely offline, and words it ignored are listed rather than silently dropped.
    • A saved view can become a Clean Up rule, and a Clean Up rule can become an Autopilot policy, pre-filled.

    The cleanup cart

    • An optional cleanup target in Settings ("free 50 GB") gives the cart a meter filling toward it. A meter and nothing else: no streaks, no badges, no confetti.
    • Add to cart from every view that lists something reclaimable — Empty Folders, Clean Up rule matches, per-game shader caches, and "Stage N matches" from a treemap query.
    • Preview after. The map re-lays itself with the staged items taken out, and the freed space stays on the map as a hatched block, so every rectangle still means the same number of bytes.
    • Committing the cart runs through the Time Capsule as one undoable run — a dry run first, always, then one summary with a one-click undo that puts everything back at its original paths, even after the Trash has been emptied. Undo restores the original dates as well as the bytes.

    New views

    • Missing GB. One accounting statement for the volume, printed as a receipt that either adds up or names the gap. It shows what a files-only tool cannot: other volumes sharing the same storage pool (about 12 GB on a Mac), space held by programs still gripping a deleted file, and what the scan was refused. A line nobody can measure prints "unknown" with its reason — never 0.
    • Disk City. The treemap's ow
  4. v3.2.1v3.2.1 Enhanced Speed2026-08-26 · 2026-08-26 02:03 UTC

    这个版本没有写更新说明。

  5. v3.2.03.2.02026-08-26 · 2026-08-26 00:53 UTC

    这个版本没有写更新说明。

用户点评

登录用户的真实使用记录,可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译

       

    ⬇ Download   ✨ Features   🧩 VS Code   🚀 Run it   🤖 AI / MCP   🛡️ Safety

    [!TIP] No Node. No setup. No telemetry. The desktop app is fully self-contained and scans the disk of the machine it runs on. Deletes always go to your system Trash, nothing is ever hard-deleted, and anything moved there can be put back until the Trash is emptied.

    Screenshots follow your GitHub theme: switch between light and dark to see both.

    ✨ The seventeen views

    TreeMap isn't just a treemap, it's a full disk-hygiene workbench. Press ⌘K (Ctrl+K) to jump anywhere. Sizes are decimal, as Finder counts them (1 GB = 1,000,000,000 bytes).

    ViewWhat it does
    📊 DashboardDisk ring, file types, the largest files and folders, a disk-full forecast, Cost to keep, Drive health and folder budget gauges
    🗺️ TreemapEvery file sized by its bytes. Drill in, search, lasso into the cart, scrub a time slider, watch live changes, look inside archives. Also draws as Sunburst, Circles or Voronoi
    🏙️ Disk CityThe same layout as an isometric city: footprint is bytes, height is staleness
    🔲 GridA size-proportional icon grid, sortable by size, date or Reclaim score
    📦 AppsHow much disk each app owns: app, caches, data and logs, with a safe cache clear
    🎮 LibrariesSteam, Epic, GOG, itch.io and media libraries; only the parts that regenerate are offered
    🛡️ SecurityKeys and credentials outside the folder they belong in, found by name and location only
    🌐 FleetHow full your other computers are, over your network. Off by default, summaries only
    🥧 Missing GBWhy "used" and the files you can see don't add up, as a receipt that balances or names the gap
    🧬 DuplicatesTrue duplicates by SHA-256, near-duplicate images, and a side-by-side Compare
    📈 TrendsEvery scan charted over time: what grew, what shrank
    🗓️ HistoryA calendar of bytes written per day, a journal of big changes, and a diff of any two scans of a folder
    📤 OffloadedFiles moved to another drive: copied, verified byte for byte, then the originals trashed
    🗄️ Undo VaultA verified copy of what the Clean Up cart and Autopilot trash, kept 30 days by default, or less to stay under its size cap
    ✨ AutopilotClean Up rules that keep running, with a mandatory first preview and byte caps
    🧹 Clean UpSmart suggestions, custom rules, a Reclaim score that explains itself, and a cart that dry-runs before anything moves
    ⏰ Scheduled + IgnoreRescans on a schedule with growth alerts, and a list of paths and globs to skip

    📖 Every view in detail, and the limits each one states: docs/FEATURES.md

    How it's built: Node.js + Express 5 + TypeScript, with a Rust scan core. The frontend is a single, zero-dependency index.html, generated from src/ui/, with hand-coded Canvas 2D. Ships as a web app and a downloadable Electron desktop app for macOS and Windows.

    ⬇️ Download the app (for users)

    Grab the latest installer from the Releases page:

    [!NOTE] Intel Mac? The macOS build is Apple Silicon only: any M-series Mac (late 2020 onward). Not sure? About This Mac says either Apple M… or Intel. On an Intel Mac, run TreeMap in web mode (three commands, below): it is the same app in a browser tab.

    Linux, no desktop download: use web mode too, or build your own AppImage with npm run dist:linux.

    Every release also carries a portable Windows TreeMap-x.y.z.exe (no installer, keeps its data beside itself).

    Which version do I have? In the desktop app: TreeMap → About TreeMap on macOS, Help → About TreeMap on Windows. In web mode, open http://127.0.0.1:4280/api/capabilities (or the PORT you set) and read version; that is the number on the Releases page.

    🍎 First launch on macOS: "Apple could not verify…"

    The first time you open TreeMap, macOS says "TreeMap.app" Not Opened. Apple could not verify…

    Your download is fine. macOS shows that for any app that isn't notarized, and notarizing needs a paid Apple Developer membership this free, open-source project doesn't have. Every byte is public in this repo, and every release is built in the open by GitHub Actions. Get past it once with either route below; after that TreeMap opens normally.

    ⚠️ Right-click → Open no longer works. Apple removed that shortcut in macOS Sequoia (15). And the Open Anyway button in step 3 only shows for about an hour after the block: if it's gone, double-click TreeMap again, then go straight back to System Settings.

    1. Double-click TreeMap in Applications. When the message appears, click Done.
    2. Open System Settings → Privacy & Security and scroll to Security at the bottom.
    3. Next to "TreeMap.app" was blocked to protect your Mac, click Open Anyway, and authenticate.
    4. Double-click TreeMap again, click Open Anyway on the last prompt, and authenticate once more.

    With TreeMap in Applications, open Terminal (⌘-Space, type Terminal) and paste:

    xattr -dr com.apple.quarantine /Applications/TreeMap.app
    

    Nothing prints when it works; double-click TreeMap and it opens. This removes macOS's "came from the internet" marker from TreeMap only. It changes no setting, weakens nothing else, and needs no password.

    Same cause, use Route 2. If it still says damaged after that, the download was truncated: delete the .dmg and download it again.

    Both routes work, and so does the classic shortcut Apple removed in Sequoia: right-click TreeMap → Open → Open.

    🪟 First launch on Windows: "Windows protected your PC"

    The installer isn't signed with a paid Microsoft certificate, so SmartScreen shows a blue box once. Click More info, then Run anyway.

    🖥️ Desktop extras

    • 📌 Tray icon with live free space; close the window and scheduled scans keep running.
    • 🖱️ Drag & drop a folder onto the window to scan it, or use "Scan with TreeMap" from the right-click menu (add it in Settings).
    • 🔄 Auto-updates from GitHub Releases. Windows downloads and asks before restarting; macOS can't install into an un-notarized app, so it checks and offers a Download dialog that opens the Releases page.
    • 🧳 Portable, no-trace mode: run it from a USB stick and it writes nothing to the host machine.
    • ⚙️ Scanning budget (Eco, Balanced, Turbo or Automatic) and engine choice, in Settings.

    🧩 Inside VS Code

    The extension in vscode-extension/ runs TreeMap's own server and shows the visualizer in an editor tab.

    cd vscode-extension
    npm install && npm run compile
    npx @vscode/vsce package --no-dependencies   # produces a .vsix you can install
    

    Then Extensions → ⋯ → Install from VSIX…, and run TreeMap: Open Disk Visualizer from the command palette, or right-click a folder in the Explorer for TreeMap: Scan This Workspace Folder.

    The first open clones and builds TreeMap under one cancellable progress notification (if the open folder is this repository, your working tree is used as is). The server runs as a child process on your own Node 20+, never inside the extension host, because its native modules need standard Node.

    🚀 Run from source / web mode (3 commands)

    npm install
    npm run build
    npm start
    

    Then open http://127.0.0.1:4280 in your browser. For development with auto-reload: npm run dev.

    Requires Node.js 20+. Trash support uses gio on Linux (preinstalled on GNOME/KDE), Finder on macOS, and the Recycle Bin on Windows. A copy run from source scans with the built-in walker (or, on macOS and Linux, gdu, if npm run fetch:gdu:dev fetched one or it is on your PATH); to build the faster native engine, install Rust from https://rustup.rs and run npm run build:native.

    📦 Build the desktop app

    npm install
    npm run app          # build + launch the desktop app locally
    npm run dist:mac     # produce a macOS .dmg in release/
    npm run dist:win     # produce a Windows installer in release/
    

    ⚠️ Build the macOS app on a Mac and the Windows app on Windows. Packaging needs Rust (rustup.rs); installing or running TreeMap never does.

    To publish a release for both platforms from GitHub Actions, follow docs/RELEASING.md.

    🤖 Use it with AI (MCP)

    TreeMap speaks the Model Context Protocol (MCP), so AI assistants like Claude can use it as a tool. Connect it once and talk to your disk:

    "What's eating my disk?"  ·  "Find duplicates in my Downloads and clean them up"  ·  "How long until this disk is full?"

    Every safety rule still applies: deletes only go to the system Trash, destructive actions can be dry-run first, and everything is written to an audit log.

    Step 1: One-time setup (~2 minutes)

    You need Node.js 20+. In a terminal:

    git clone https://github.com/Prithvi-Web/TreeMap-Disk-Visualizer.git
    cd TreeMap-Disk-Visualizer
    npm install
    npm run build
    pwd
    

    The last line prints the folder's full path: use it wherever you see /PATH/TO/TreeMap-Disk-Visualizer below.

    Step 2: Connect your AI app

    1. Open Claude Desktop → Settings → Developer → Edit Config. That opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).
    2. Add TreeMap to it (if the file already has an mcpServers block, just add the "treemap" entry inside it):
    {
      "mcpServers": {
        "treemap": {
          "command": "node",
          "args": ["/PATH/TO/TreeMap-Disk-Visualizer/dist/mcp/index.js"]
        }
      }
    }
    
    1. Fully quit and reopen Claude Desktop. TreeMap's tools are listed under treemap.

    🪟 Windows: write the path with double backslashes, e.g. "C:\\Users\\you\\TreeMap-Disk-Visualizer\\dist\\mcp\\index.js".

    claude mcp add treemap -- node /PATH/TO/TreeMap-Disk-Visualizer/dist/mcp/index.js
    

    Next session, ask Claude Code to scan a folder. (claude mcp list shows it; claude mcp remove treemap undoes it.)

    Create (or edit) .cursor/mcp.json in your home folder for all projects, or in a project's root for just that project:

    {
      "mcpServers": {
        "treemap": {
          "command": "node",
          "args": ["/PATH/TO/TreeMap-Disk-Visualizer/dist/mcp/index.js"]
        }
      }
    }
    

    Then enable it under Settings → MCP.

    TreeMap is a standard stdio MCP server: command node, argument /PATH/TO/TreeMap-Disk-Visualizer/dist/mcp/index.js. No environment variables, ports or API keys. (Smoke test from the repo folder: npm run mcp should print server ready on stdio.)

    What the AI can do

    ToolWhat it does
    scan_pathScan a folder → returns a scanId the other tools use
    get_largestThe biggest files or folders in a scan
    reclaim_rankedEntries ranked by Reclaim score, safest to delete first, with the breakdown
    find_duplicatesTrue duplicates (size + SHA-256 content hashing)
    cleanup_suggestionsKnown-reclaimable space: caches, regenerable build folders, junk
    forecastDisk-full projection: "full in ~58 days at current growth"
    missing_gigabytesWhere the used space went, line by line; an unknown is null with its reason, never 0
    compare_scansWhat grew and what shrank between two scans
    offloadMove files to another drive: copy → verify → then trash originals
    trash_pathsMove files to the system Trash, never a hard delete

    The AI can only touch paths inside folders it has scanned; trash_paths and offload accept dryRun: true to show the plan first; an agent-policy.json can limit it further; and every destructive request lands in an append-only audit.jsonl. AGENTS.md is the full guide.

    🔌 API

    Prefer plain HTTP? Everything is a local REST API (npm start, then /api/*). Every endpoint is in docs/API.md; the machine-readable spec is at /api/openapi.json.

    🛡️ Safety

    Disk tools should never lose your data. TreeMap is built defensively:

    • ♻️ Deletes always go through the OS Trash: undo from Finder or Explorer until the Trash is emptied.
    • 🎯 Trash and open only accept paths inside a folder you scanned, never paths inside an archive.
    • 🔒 Paths are sanitized; system folders (/proc, /sys, /dev, /run, C:\Windows\System32, …) are blocked, but not /run/media, where Linux mounts a person's own drives.
    • 📤 Offload copies, verifies every byte with SHA-256, and only then trashes the originals; a failure before every copy verifies rolls back.
    • 🧬 Duplicates always keeps at least one copy, and never opens an online-only file (that would download it).
    • ☁️ Cloud scanning is opt-in and metadata-only, and cloud deletes go to the provider's own trash; with no account connected, no cloud code runs.
    • 🚦 Per-client rate limiting (10 requests/s for the API, bursts of 20) and graceful shutdown.
    • ⏳ Scan results live in memory only and expire after 30 minutes; what's saved stays in the app-data folder on your machine. SECURITY.md lists every file and every outbound connection.

    🗂️ Contributing

    CONTRIBUTING.md has the three commands and the one rule. docs/ARCHITECTURE.md has the project layout and the design decisions behind it.

    📜 Licence

    MIT, see LICENSE. The desktop app also bundles gdu, the native scan core's Rust crates, Electron and Chromium, each with its licence inside the app; docs/ARCHITECTURE.md says where.

    Found this useful?

       

    TreeMap  ·  built with 🟩🟨🟥 by Prithvi-Web

    If TreeMap freed up a few gigs for you, a ⭐ goes a long way.