TreeMap Disk Visualizer: an Electron treemap app with an MCP server and a Docker scan mode

The problem TreeMap solves, and the people it is aimed at

A full disk is rarely one big file. It is a cache directory, an old VM image, three copies of the same export, and a node_modules tree you forgot about. TreeMap's answer is a squarified treemap of every byte, wrapped in a desktop app that also lets you open files and send unwanted ones to the system Trash. The README frames the whole thing as three moves: find it, understand it, reclaim it.

The audience is broader than the usual command-line crowd. The README advertises downloads for macOS arm64 and a Windows installer, with Linux handled through web mode rather than a native package. The repository topics list electron, typescript, disk-cleanup and data-visualization, and the package description calls it a desktop app for macOS and Windows with web mode on Linux. If you are comfortable with `du` and `ncdu`, the visual layer is a convenience. If you are not, the treemap is the entire point: size becomes area, so the biggest offender is the biggest square, and no sorting is required to see it.

How the Electron app, the Express server and the MCP server fit together

The layout is a single TypeScript codebase with three entry points. `electron/main.js` is the desktop shell. `src/index.ts` is the Express 5 server that backs web mode, started in development with `tsx watch src/index.ts` and in production with `node dist/index.js`. `src/mcp/index.ts` is a Model Context Protocol server, so an AI agent can call the same scanning and analysis surface the UI uses. The frontend is described as zero-dependency and is stitched into `public/index.html` by `scripts/build-ui.js` at build time, which is why the Dockerfile copies `public` from the build stage rather than from the host.

That last detail is the most interesting engineering decision in the repository. The Dockerfile comment states that taking `public/index.html` from the build stage is what keeps the image honest, because a stale artifact on the host can never ship. Build steps that generate committed assets are a common source of drift, and this closes it.

The scan itself is not written in TypeScript alone. The `dist` scripts run `npm run fetch:gdu` before electron-builder, and the container sets `TREEMAP_NO_GDU=1`. So the desktop build pulls in a gdu binary, while the server image deliberately runs without it. That is a real capability split between the two delivery modes, and the README does not spell out which views degrade when gdu is missing.

Installing TreeMap from source and taking a first scan

The README points end users at the GitHub releases page for a downloadable build, and package.json carries the scripts for running from source. The dev server is the fastest way to see the UI without packaging anything.

npm install
npm run dev

The `dev` script runs `tsx watch src/index.ts`, so you get the Express server with live reload. The README's run-from-source section is titled around three commands, and the build path is the other one to know: `npm run build` runs `build-ui`, then `tsc`, then `copy-assets`, and `npm start` runs the compiled `dist/index.js`.

If you want the actual desktop shell rather than a browser tab, the `app` script builds and launches Electron in one step.

npm run app

For a distributable, the `dist` script runs the build, fetches gdu, and calls electron-builder with `--publish never`, with `dist:mac`, `dist:win` and `dist:linux` variants. The README does not document rollback for a bad build, and nothing in the repository describes a migration path for the `treemap-data` volume if a release changes its on-disk format. Treat upgrades as replace-and-rescan until that is documented.

Running TreeMap in Docker, and why that mode is scan-only

The compose file is short and unusually opinionated. It publishes the port on `127.0.0.1` only, so nothing outside the machine can reach the server by default, and it mounts a named volume at `/data`.

services:
  treemap:
    build: .
    container_name: treemap
    ports:
      - "127.0.0.1:4280:4280"
    volumes:
      - treemap-data:/data
    restart: unless-stopped

Both the compose file and the Dockerfile are explicit that a container has no OS Trash and no display, so the container profile should be treated as scan-and-analyze, with destructive cleanups done from the desktop app. The image sets `HOST=0.0.0.0`, `PORT=4280`, `TREEMAP_DATA_DIR=/data` and `TREEMAP_NO_GDU=1`. To expose it beyond localhost you change the mapping to `"4280:4280"` and set `TREEMAP_TOKEN`, which the compose comments describe as bearer auth for `/api`. `TREEMAP_ALLOWED_ORIGINS` is the other variable shown, commented out, for a specific origin such as `https://tools.example.com`.

This is the right call. A web server that deletes files on a mounted volume, with no Trash to fall back on, is a footgun. The documentation says so instead of pretending otherwise.

The forecasts and health panels refuse to guess, which is the app's best trait

The Dashboard carries a disk-full forecast that projects from scan history. The README gives the shape of the output, including a growth rate in GB per day and a projected number of days until full, and then states the conditions under which it declines to produce a number: too little history, erratic growth, or shrinking usage. Folder budgets reuse the same projection code, with `src/services/budgetGauges.ts` calling `computeForecast` verbatim and the budget headroom standing in for free space, so the refusals carry over.

Drive Health is the same posture. It reports the drive's SMART attributes and self-assessment verbatim and answers one question: which runs out first, free space or write endurance. Where the numbers are not available, because `smartctl` is missing or the drive reports no wear indicator, the README says it states exactly that. The stated reason is that a false warning about a dying drive is a real harm.

Most disk tools in this category are happy to invent a scary number. Refusing to is a design choice, and it is the one that makes the dashboard trustworthy enough to leave open. The cost is that on machines with short scan history, the forecast card will mostly tell you it cannot help yet.

Where TreeMap is the wrong tool

The Linux badge in the README says `web_mode`, not a packaged desktop build. If you want a native Linux binary with a system Trash integration, the repository does not describe one. You get the server and the browser UI, or you build Electron yourself.

The Docker profile is the second wrong-tool case, and the repository says so directly: no OS Trash, no display, scan and analyze only. Anyone expecting the container to replace the desktop cleanup flow will be disappointed by design, not by bug.

The third case is raw scan throughput. The release notes include a v3.2.1 titled Enhanced Speed and a v5.0.0 named Disk City, and the build fetches a gdu binary for the desktop target, which suggests scanning is delegated to a native tool. But the README does not publish a comparison against WizTree or any other analyzer, and no benchmark numbers appear in the repository. If you are scanning multi-terabyte volumes on Windows and speed is the deciding factor, this project gives you nothing to check that against. The v5.0.1 release is titled Minor Bug Fixes, so the current line is a bug-fix release on top of Disk City.

TreeMap against WinDirStat, WizTree and the rest of the category

The obvious comparison is WinDirStat, which the related searches pair with this project constantly. WinDirStat is Windows-only and its interface is a directory tree plus a treemap plus an extension list, all in one window. TreeMap spreads the same job across seventeen views, with a command palette on Cmd+K or Ctrl+K that indexes views, settings sections, actions and previously scanned folders, and falls back to a file search for anything it does not recognise. That is a different bet: more surfaces, more discoverability machinery.

WizTree's distinguishing claim in this category is reading the NTFS master file table directly, which is a fundamentally different scanning strategy from walking the filesystem. The repository says nothing about TreeMap reading filesystem metadata directly, and the presence of a separate gdu fetch step points the other way. So the honest framing is that TreeMap competes on interface and integrations, not on a low-level scanning trick.

GrandPerspective and TreeSize Free occupy the same visual-analysis ground on macOS and Windows respectively. Neither appears in this repository, so the only defensible statement is that TreeMap's differentiator is the combination of a cross-platform Electron app, an MCP server for agents, and a documented container profile. If you do not want an AI agent poking at your disk, that differentiator is worth nothing to you.

Licence, upgrade cost and what the MCP server implies

The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are kept. That is the whole of it; nothing in the repository describes a separate licence for the gdu binary that the build downloads, and if you redistribute a packaged build you should check that dependency's own terms rather than assume MIT covers it.

The upgrade cost is low if you use the downloadable builds: the release history shows v5.0.1 on 2026-09-08, v5.0.0 on 2026-09-03 and v3.2.1 on 2026-08-26, and the last push to the repository was on 2026-09-08. There is no documented data migration between versions, so the practical upgrade path is to install over the old build and accept a rescan.

The MCP server is the piece that changes your threat model rather than your disk. Running `npm run mcp` exposes the same analysis surface to an agent, and the compose comments point at AGENTS.md for the full server profile and its threat model. If you enable the network-facing server, `TREEMAP_TOKEN` is the only authentication mechanism the repository describes. Read AGENTS.md before widening the port mapping, not after.

Editorial conclusion

Adopt TreeMap if you want a cross-platform treemap you can also drive from an AI agent over MCP, and if you accept that the Linux story is web mode rather than a packaged desktop build. Skip it if you need Windows-only raw NTFS speed, or if you plan to run destructive cleanups from the Docker image, which ships without an OS Trash and is documented as scan-and-analyze. Verify the two things the README leaves open before you commit: whether the packaged Electron build ships with the gdu binary, since package.json has a separate fetch:gdu step, and whether the SMART panel works on your machine, since it says so plainly when smartctl is absent.

Frequently asked questions

Official sources

1. License: MIT
2. Prithvi-Web/TreeMap-Disk-Visualizer on GitHub
3. Project website
4. README
5. Releases