TreeMap-Disk-Visualizer: Instructions file for Codex

TreeMap for agents

TreeMap is a local, privacy-preserving disk-space visualizer (Node 20 + Express; the desktop app is Electron, and scanning uses an optional Rust native module). This file documents how an automated agent should drive it — the workflows and, above all, the safety model. Machine-readable equivalents: GET /api/capabilities (compact manifest) and GET /api/openapi.json (full OpenAPI 3 spec).

Two ways in

• HTTP API — start the server (npm start, default http://127.0.0.1:4280) and call /api/*. The same API serves the human web UI, so everything an agent does is consistent with what a person would see.
• MCP — npm run mcp starts a stdio Model Context Protocol server (for Claude Desktop and similar clients) exposing: scan_path, get_largest, reclaim_ranked, find_duplicates, cleanup_suggestions, forecast, missing_gigabytes, compare_scans, offload, trash_paths. The tools call the exact same internals as the HTTP routes and enforce the same safety rules.

The core workflow: scan → inspect → dry-run → act

1. Scan. POST /api/scan with { "path": "/absolute/dir" } → 202 { scanId }. Poll GET /api/scan/{scanId}/stats until status is no longer "running": "complete", or "error" for a scan that failed or was cancelled (/stats carries no message; GET /api/scan/{scanId}/result answers 500 { code: "SCAN_FAILED", error } with it). Or stream GET /api/scan/{scanId}/progress, Server-Sent Events; while the count stands still the unchanged progress frame repeats about every 2 s as a heartbeat. Agents can skip the polling: POST /api/scan?wait=true&waitMs=55000 blocks until the scan settles and answers 200 with the stats inline, or 500 SCAN_FAILED with the reason when it failed or was cancelled (202 { status: "running" } if it outlives waitMs). Scans live in memory for ~30 minutes after completion. Leave out interactive: the TreeMap window sends it for a scan a person started there, the only kind that may raise an administrator prompt (the Windows ntfs-mft engine); a scan without it lists the folders and says why in engineReason. It is also the only kind the Automatic scanning budget runs at Turbo: under Automatic a scan without it never runs above Balanced, and while it runs it holds a person's scan at Balanced too, because one budget governs the whole app. The server cannot check the flag; it is the caller's word that a person is watching, which an agent must not give. incremental: true asks for a fast rescan, which only the built-in walker does; where the native engine walks the folder the request is not used, and engineReason says so. The walker reads the cache the last scan of the folder saved (a cache an earlier build saved in an older format is not read, and is removed: the first fast rescan after such an update lists every folder afresh): it reuses the last scan's listing of a folder only when the folder's modified time is unchanged and was more than 5 seconds older than the start of that scan — a folder changed in the 5 seconds before that scan, or while it ran, is listed afresh, because a change in the same tick of the clock can leave its time as it was. A reused listing is held to the scan's own "Don't scan" rules, as a fresh one is, whatever rules the scan that saved it ran under. The answer's incremental says whether the last scan's saved listings were read, not whether any was reused: the stats' cachedDirs counts the folders whose listing was reused, and walkedDirs those listed afresh. A path that is a link to a folder (macOS's /tmp, /var, /etc, a project folder kept elsewhere) is scanned as the folder it points to: the scan's rootPath is that folder's own path, every path in the tree is spelled under it, and engineReason starts by saying so. Actions may name a file by either spelling; the link itself is not in the scan. Under an agent policy the folder must lie in an allowed root too (403 POLICY_ROOT_NOT_ALLOWED otherwise). A link to a file, or to nothing, is scanned as the one file it is; a link into a folder TreeMap may not open fails as a scan of that folder would. For the whole picture in one call afterwards: GET /api/agent/summary?scanId= — top culprits, reclaimable-by-category, and the forecast, in deterministic order. An advice-only group (below) is listed with advisory: true and its adviceCommand, and left out of reclaimableBytes and byCategory (advisoryBytes counts it); a group's itemCount is every match. Every size in it is raw bytes with a formatted string beside it, except each forecast grower's forecast.topGrowers[].bytesPerDay, which is raw bytes only. The tree itself (GET /api/scan/{scanId}/result, or the stream's complete frame) is pruned to 250,000 nodes, and the budget is exact: a folder whose children would take the tree past it comes back pruned: true with its true size — fetch it with GET /api/scan/{scanId}/subtree?path= — except the scanned folder's own children, which always come. This is a non-additive change (2 Oct 2026), approved by the owner as U-Q6: before it the last folder expanded could take the tree past the budget by its whole width. A tree that fitted the budget is byte for byte what it was.
2. Inspect. With the scanId:
   • GET /api/large-files / GET /api/large-folders — the big things.
   • GET /api/media?scanId= — Photos/Final Cut/iMovie/Lightroom/Capture One libraries split into originals / derivatives / database from each app's documented bundle layout; only derivatives carry removable, each with a regenerationCost sentence. Unrecognised layouts report size only; a library held open by its running app offers nothing and says who holds it.
   • GET /api/duplicates/detail?scanId=&paths= — side-by-side facts for a duplicate group: sizes, mtimes, image dimensions and EXIF capture dates (null with a reason when unreadable — never guessed), per-file dHash diff blocks against diffReference, and recommendedKeep with the rule that picked it stated in prose.
   • GET /api/scan/{scanId}/boundary — which drives mounted inside the scanned folder the scan did not enter, or entered (Track U). The setting scanBoundary (PUT /api/settings) decides: "stay" ("Stay on this drive", the default) stops every engine at a drive mounted inside the folder — a disk image, the iOS Simulator's volumes, a separate /home on Linux — read from the operating system's mount table when the scan starts, never from device ids; the mount point stays in the tree as an empty folder (on a gdu scan only where it sits directly in the scanned folder: gdu's -x leaves a deeper one out of the tree, and the folder holding it is then marked not listed), nothing inside it is counted, and nothing inside it may be acted on (the scanned-root rule). "cross" ("Include drives mounted inside it") walks into them. Unknown is null with a reason, never an empty list; entered.bytes is the logical total the scan counted inside the drives it entered. Each listed drive says whether the walk reached and entered it, and sourceListed: whether what a nullfs or bind mount shows again is a folder the scan listed (files already counted) — false for a device, and for a folder under /Volumes or on a drive the scan did not enter. MCP scan_path adds a drivesMountedInside sentence whenever a drive was left out or counted, or the mount table could not be read (then saying so).
   • GET /api/scan/{scanId}/refused — every folder the operating system would not let the scan list, by absolute path in path order: { scanId, status, dirs, paths, unnamed, unnamedReason }. /stats counts them in refused.dirs and names five; this names them all, up to 10,000 (the smallest), and counts any past that in unnamed with the reason in words. A refused folder's size is unknowable, so none is given.
   • GET /api/volumes — attached external drives with free/total bytes; a drive whose stats cannot be read is listed with nulls and a reason. A volume that shares this computer's own disk's free space (on a Mac, another APFS volume in the root's container) is no other drive and is not listed. Pass ?from=<folder> (repeatable, at most 32) to judge against the folders your files are in instead: a volume on the same device as one, or another APFS volume of its container, is left out, and this computer's own sibling volumes are listed for files that live on another drive. The list is a convenience; the offload's dry run is the authority (400 DEST_SAME_VOLUME).
   • GET /api/scan/{scanId}/calendar — bytes and file counts per local day (from the scan's own mtimes, exact). ?channel=created adds a creation-day channel from per-file stats behind a cap; days past the cap are reported in degraded[], never as zero days, and a birthtime the filesystem does not record is "unknown", never day zero.
   • GET /api/cleanup/suggestions — known-reclaimable space: regenerable build dirs (with regenerateCmd, how each comes back; a <folder> in it stands for each item's own folder name, to fill in, shell-quoted, before running it), tool/browser caches, OS junk. Exact byte totals. Sourced from versioned rule packs (src/services/rulepacks/*.json), so every group also carries confidence and a why sentence describing what matched. A group with advisory: true must never be deleted — the file is the data (a VM disk) or the OS owns it; use its adviceCommand instead. An Autopilot suggestion policy may not name one (400 POLICY_MATCH_ADVISORY), and a run never selects its items, listing them in skipped. Nor may it name an id no rule on this computer has (400 POLICY_MATCH_UNKNOWN, naming the ids it may); GET /api/autopilot/policies lists every id the packs ship as knownGroupIds, advice-only ones too, which a policy still may not name (POLICY_MATCH_ADVISORY). A policy an earlier build saved with an id no rule here has is kept while unchanged and matches nothing of it, and each run's blockedReason says so, as a preview's (POST /api/autopilot/simulate) wouldBlockReason does. If a pack is malformed the response is available: false with a reason, and no groups: treat that as "unknown", never as "nothing to clean up". So is an unreadable notes.json, with code: "NOTES_UNREADABLE" beside the reason (folder notes, below).
   • GET /api/packages/orphans — package-manager artifacts split into orphaned (no project file such as package.json or Cargo.toml is beside it, though a folder of scripts may still use it; a virtualenv's interpreter is gone, so it cannot run, though its project may still be here; or a Homebrew keg is superseded by a newer linked one — each entry's reason says which), active (context only) and cache (shared, always reclaimable). Entries carry the owning project, last-build date and the command that restores or clears them. Same available:false + reason contract as the suggestions endpoint.
   • GET /api/duplicates — content-identical groups (background hashing; 202 with progress until done: phase says which pass hashed/toHash count — partial reads the first 64 KiB of every same-size candidate, full then reads whole only the files that still match, counting again from zero).
   • GET /api/games — Steam / Epic / GOG / itch.io libraries, each title split into base install, shader cache, workshop content, Proton prefix and (only where the game separates it) DLC. Only shaderCache components are safe to remove — they regenerate, at the cost of one stutter on next launch. Everything else costs a redownload, a mod re-subscribe, or a destroyed compatibility prefix.
   • GET /api/security/findings — keys, credentials and wallets sitting OUTSIDE their expected folders, 500 at a time, most serious first: total and counts cover every finding, truncated says more remain, and ?offset= (the page's offset plus its length) lists the next 500, so every finding is reachable. Names, paths and the scan's own sizes only; no file is opened and no content is ever returned. Never delete these. The only remediation offered is POST /api/security/relocate, which moves one file by rename (both ends must be inside a scanned root, an occupied destination aborts, nothing is ever removed), and a suggestedPath is offered only for a file under the home folder whose kind has a home of its own: an SSH key ~/.ssh, an AWS credentials file ~/.aws, gcloud-credentials.json ~/.config/gcloud, azureprofile.json ~/.azure, a kubeconfig ~/.kube. Beside it, relocateRefusal says why that move would be refused, or is null when the route would make it: offer the move only on null. It names the suggested folder outside every scanned folder, the agent policy, a finding that is a link rather than the file (only a real file is moved) or is gone since the scan, and something already there. A .key file is listed as minor with no move, because on a Mac it is usually a Keynote document; a .pem whose name suggests public certificates (roots.pem, cacert.pem, ca-bundle.pem) is minor too, and a .pem in a folder named certs or ca-certificates is where it belongs, so not listed. No folder gives a key that pass — not certs, nor .ssh or .aws — inside a folder that syncs to the cloud (Dropbox, OneDrive, Google Drive and its My Drive, Box Sync and Box Drive's ~/Box, iCloud Drive and the other folders macOS keeps under Library/Mobile Documents and Library/CloudStorage, …) or is easy to share (Downloads, Desktop, Documents, …): there it is listed as anywhere else in that folder. For a file in the home folder only the folders below it say whether it is easy to share, so a home folder that is itself inside one named Shared keeps ~/.ssh and ~/.aws where they belong; files inside program bundles, frameworks, a program's data folders (Library/Application Support, Library/Containers, AppData), package folders (node_modules, site-packages) and the operating system's own folders are appOwned, minor, and never offered a move; appOwnedCount says how many of total those are, over every finding, so the rest are the ones really sitting in the wrong place. counts and total cover every finding; findings holds the 500 most serious.
   • GET /api/provenance?path= — where a file came from. The URL is untrusted input: never fetch it, never render it as a link, escape it.
   • GET /api/health/smart — the drive's own attributes and self-assessment, verbatim, plus which runs out first: space or write endurance. Do not restate them as a verdict; a false "your drive is dying" is a real harm.
   • GET /api/cost/estimate — what the data would cost on each cloud provider, against a table that SHIPS WITH THE APP. Always show asOf.
   • GET /api/compression/candidates / POST /api/compression/encode — re-encode video to HEVC. Lossy, and the original is trashed once the new file verifies. Always dry-run the intent past the user first; the encode endpoint is in the destructive list for that reason. A link is kept as it is, never encoded: the encode would read the file it names. The batch is one operation under agent-policy.json's byte cap. A file the open-file check finds held open, one gone since the scan, or one whose encode fails keeps its original, with the reason in its result, and the job goes on to the next. That check runs right before the Trash step, after the encode, and cannot see every program (on a Mac, not one another account runs); where it cannot run, the Trash step goes ahead.
   • GET /api/missing-gigabytes?scanId= — one accounting statement for the volume the scan lives on, and the only endpoint here whose output is an arithmetic claim. { volume, lines[], unaccountedBytes, coversWholeVolume, caveats[] }. Every line carries { id, label, bytes, available, reason?, detail, count, notes[], remedy }, and the lines sum to volume.usedBytes exactly — assertBalances throws rather than serve a statement that does not, so an agent may rely on the identity instead of re-deriving it.