Skip to content

A treemap for finding and removing what fills your disk, for Omarchy. Rust + GPUI.

Rust

README, agent guide and MIT license

Tobi Lutkea2b03f3e8c14
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..30a5414
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,106 @@
+# disktree — agent guide
+
+A GPUI + gpui-omarchy treemap explorer for disk usage on Omarchy. Read
+`README.md` for the product; this file is the working contract.
+
+## What this is
+
+Find what is eating a volume, mark paths for removal, review the list, and
+remove it — with the volume's free space live on screen the whole time. Two
+phases: explore (treemap, breadcrumbs, the selection and status lines) and review (the marked list,
+the removal mode, the confirmation). Marking is never destructive.
+
+## Commands
+
+```sh
+make build # release build
+make run # build and run, scanning $HOME
+make install # ~/.local: binary, desktop entry, icon
+make install PREFIX=/usr/local # system-wide (needs root)
+make uninstall
+make lint # rustfmt --check, then clippy --all-targets -D warnings
+make test # core and window-harness tests
+make ci # lint, then test
+make fmt # format in place
+```
+
+`make install` is the supported way to put this on a machine: it installs the
+release binary, `packaging/disktree.desktop.in` (rendered with the real install
+prefix and the crate version) and `assets/disktree.svg`. Keep the desktop
+entry's `Categories` to a single main category plus additional ones, or
+`desktop-file-validate` complains.
+
+`cargo xtask lint` is the gate. It must be green before anything is called
+done, and it must not fix anything: a red local run is the same signal CI gives.
+
+## House rules
+
+* **Strict lints from omatrack's style.** `clippy::all` and `clippy::pedantic`
+ are errors, `clippy::nursery` warns, and `-D warnings` promotes the rest. Every
+ deliberate exception is listed with its reason in the workspace `Cargo.toml`
+ or as an `#[allow(..., reason = "...")]` on the item — never silently.
+* **80 columns**, 4-space indent, by `rustfmt.toml`. Only stable rustfmt
+ options, because the gate runs on stable; unstable options would be ignored
+ with a warning instead of applying.
+* **Comments say why.** The code says what. Any non-obvious number, ordering or
+ boundary deserves the reason next to it.
+* **Tests live beside the promise they make.** `disktree-core` tests size
+ accounting, layout and deletion guards against real temporary trees;
+ `disktree-app/src/tests.rs` drives the real window harness — draw a frame,
+ press keys — so a screen that panics while painting fails a test.
+* **Never delete anything outside a marked path.** See `removal.rs`; the guards
+ are load-bearing and are covered by tests.
+
+## Invariants
+
+1. **Sizes come from `st_blocks * 512` unless apparent size was asked for.**
+ That is the number that comes back when a file is deleted.
+2. **`own_bytes`/`own_files` are derived, never tracked.** `tree::aggregate`
+ computes the totals from the children. Hardlink de-duplication rewrites a
+ leaf's weight and re-aggregates; anything that patches `bytes` directly will
+ be overwritten.
+3. **A directory is only built when its own scan *and* every subdirectory task
+ has finished.** That is the `+1` sentinel in `PendingDir::pending`. Building
+ early silently drops whole subtrees — it has happened once.
+4. **Only paths under the scanned root may be removed**, and mount points, the
+ root, the home directory and symlink targets are refused.
+5. **Marks are keyed by absolute path**, not tree position, so they survive a
+ re-scan; `Marks::refresh` re-reads their sizes and drops what is gone.
+6. **The treemap is painted, not composed of elements.** Thousands of
+ rectangles belong in one canvas callback; labels are shaped there too so they
+ clip to their own tile.
+7. **Tile crumbs are absolute.** `treemap::layout` takes the drawn node's
+ crumbs and every tile extends them, so a tile resolves from the scanned
+ root at any depth. Relative crumbs look right at `~` and silently point
+ at other directories after descending — including for marks. Any code that
+ turns a path into crumbs walks from the scanned root, too.
+8. **The view transform is the only thing zoom changes.** Layout runs in
+ base-space pixels and is cached; `screen = (base - origin) * scale`.
+9. **The status bar never claims a saving it cannot measure.** Projections come
+ from marked bytes; the final number comes from `statvfs` before and after.
+
+## Where changes belong
+
+| change | where |
+| --- | --- |
+| measurement, filtering, parallelism | `crates/disktree-core/src/scan.rs` |
+| what a node is, or a derived total | `crates/disktree-core/src/tree.rs` |
+| tile geometry, nesting, the merged tail | `crates/disktree-core/src/treemap.rs` |
+| anything that deletes, or refuses to | `crates/disktree-core/src/removal.rs` |
+| free space and projections | `crates/disktree-core/src/space.rs` |
+| a key, a screen transition, a mark | `crates/disktree-app/src/state.rs` |
+| spacing, type and size | `crates/disktree-app/src/ui.rs` — tokens only, no `px` in layout |
+| the mosaic's painting or labels | `crates/disktree-app/src/treemap_view.rs` |
+| layout of a screen | `crates/disktree-app/src/views.rs` |
+| colours derived from the theme | `crates/disktree-app/src/palette.rs` |
+
+## Verification expectations
+
+* Size accounting, hardlinks, symlinks, hidden entries, depth limits, the
+ removal guards and squarified layout are covered by `disktree-core` tests
+ against real temporary trees.
+* The screens are covered by window-harness tests that draw frames and press
+ keys, including one that marks a directory, confirms the removal and checks
+ the files are gone while unmarked neighbours are untouched.
+* Rendering was verified by those tests and by running the app against a real
+ home directory; it has not been eyeballed in every theme and font size.
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..55611cc
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobi Lütke
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3fb643f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,191 @@
+# disktree
+
+Find what is filling a disk, mark what should go, and remove it — with the
+volume's free space in view the whole time.
+
+disktree is a treemap for Omarchy. It scans your home directory by default,
+draws every directory as a nested mosaic sized by what it really costs on disk,
+and lets you walk into it with the keyboard or the mouse. Mark as much as you
+like; nothing happens until you review the list and commit, and the permanent
+path always asks first.
+
+Built with [GPUI](https://gpui-kit.com/) through
+[gpui-omarchy](https://github.com/huacnlee/gpui-omarchy), so it follows your
+Omarchy theme and behaves like the rest of the desktop.
+
+<!-- screenshot: assets/screenshot.png -->
+
+## Install
+
+```sh
+git clone https://github.com/tobi/disktree
+cd disktree
+make install
+```
+
+`make install` builds a release binary and puts three things under `~/.local`
+(no root needed):
+
+- `~/.local/bin/disktree`
+- a desktop entry, so disktree is in the launcher and in a file manager's
+ **Open with** for a directory (it adds a handler; it never becomes the
+ default)
+- an icon
+
+`sudo make install PREFIX=/usr/local` installs system-wide; `make uninstall`
+removes exactly what was installed.
+
+You need Rust 1.97 or newer and a Wayland or X11 session with a GPU that GPUI
+can drive (Vulkan).
+
+## Use
+
+```sh
+disktree # scan the home directory
+disktree ~/src # or any directory
+disktree --help # options: apparent size, follow links, skip hidden, …
+```
+
+### The screen
+
+- **Top:** the scan totals on the left; on the right, what is measured — rank
+ by **Size** or **Files**, **Hidden files**, **Apparent size**, and how many
+ levels are drawn. Below it, the breadcrumb: click any part to go there.
+- **Middle:** the treemap, using the full width of the window. Every directory
+ that is drawn open keeps a band at its top with its own name and size, and
+ its contents sit below that band — so a parent's name never covers a child,
+ and pointing at the band selects the parent.
+- **Bottom:** the tile you are acting on (name, path, size, its share of its
+ directory and of the scan, **Open**, **Mark for removal**); then the marked
+ total with **Review…**, the volume's free space now and after the marks, and
+ how much of the tree could be read.
+
+### Marking
+
+Space, X, Enter and the arrows act on the tile under the mouse if the mouse
+moved last, and on the keyboard selection after you use an arrow or Tab. The
+tile you mark is hatched in the danger colour. Marking is reversible — press it
+again — and a path inside a marked directory is shown as going with it, so the
+saving is never counted twice.
+
+### Zooming and going in
+
+Scroll to magnify toward the pointer. The wheel magnifies until the directory
+under the pointer fills the view, and the next notch goes into it — one
+continuous motion, with the directory's contents growing into place. Scroll the
+other way to come back out. Enter goes into the selected directory at any
+depth, and Backspace or Escape goes up one level. `+` and `-` magnify without
+going in; `0` resets.
+
+### Removing
+
+`c` (or **Review…**) opens the list of everything marked. Unmark anything
+there, then choose:
+
+- **Move to trash** — the default when a trash is available (`trash-put` from
+ trash-cli, then `gio trash`, then a built-in XDG trash). Recoverable until
+ the trash is emptied, so it commits directly.
+- **Delete permanently** — `rm -rf` semantics. It always asks first, in a dialog
+ that names what goes and how much comes back.
+
+When it finishes, disktree scans again so the numbers on screen match the disk,
+and shows how much free space was actually gained.
+
+## Keys
+
+| key | does |
+| --- | --- |
+| `space` / `x` | mark or unmark the tile you point at |
+| `ctrl`-click | mark without moving the selection |
+| `enter` | open that directory, at any depth |
+| `⌫` / `esc` | go up one directory |
+| `←` `↑` `↓` `→` | move between tiles at this level |
+| `tab` | next largest sibling |
+| scroll | zoom toward a directory, then go into it |
+| `shift`-scroll | pan the magnified view |
+| `[` `]` | draw fewer or more levels at once |
+| `-` `=` `0` | magnify, shrink, reset the view |
+| `ctrl =` `ctrl -` `ctrl 0` | interface zoom |
+| `/` | find an entry by name |
+| `c` | review the marked list |
+| `t` | rank by size or by file count |
+| `d` | disk usage or apparent size |
+| `i` | include or skip hidden entries |
+| `r` | scan again |
+| `p` | show or hide the selection line |
+| `?` | every key |
+| `q` | quit |
+
+On the review screen: `m` trash, `p` permanent, `!` unmark all, `enter`
+commits, `esc` goes back.
+
+## What it measures
+
+- **Disk usage** by default: `st_blocks × 512`, the number `du` reports and the
+ space that actually comes back when a file is deleted. Apparent size (what
+ `ls -l` shows) is one toggle away.
+- **Hardlinks once.** Two names for one inode cost one file.
+- **Hidden entries included**, because `~/.cache` is often the biggest thing in
+ a home directory. Symlinks are not followed.
+
+The scan follows [dust](https://github.com/bootandy/dust)'s approach: one rayon
+scope per root, a completion counter per directory so no directory is built
+before its last subdirectory lands, and one bottom-up pass that aggregates sizes
+and removes duplicate hardlinks.
+
+## What it refuses to do
+
+The removal rules live in `crates/disktree-core/src/removal.rs`, and each one is
+tested:
+
+- only paths under the scanned root can be removed;
+- the filesystem root, the scanned root and your home directory are refused;
+- a mount point is refused, since removing it would reach into another
+ filesystem;
+- a symlink is unlinked, never followed;
+- nothing is passed through a shell — a file called `-rf` is just a file.
+
+## On Hyprland
+
+Hyprland tiles new windows, so disktree opens into whatever tile it is given.
+It is designed for a roomy window; float it, or give it a rule:
+
+```
+windowrule = float, class:^(disktree)$
+windowrule = size 1400 900, class:^(disktree)$
+```
+
+## Develop
+
+```sh
+make run # release build, scanning $HOME
+make lint # rustfmt --check, then clippy with every warning an error
+make test # scanner, layout and removal tests, plus window-harness tests
+make ci # lint, then test
+```
+
+The lint gate is strict on purpose: `clippy::all` and `clippy::pedantic` are
+errors, and every exception is written down with its reason in `Cargo.toml`.
+The window-harness tests draw real frames and press real keys — including one
+that marks a directory, confirms the deletion and checks that the files are
+gone while their neighbours are not.
+
+| path | what lives there |
+| --- | --- |
+| `crates/disktree-core` | scanning, the tree, the squarified layout, free space and removal — no UI |
+| `crates/disktree-app/src/state.rs` | every action the interface can take, and the key map |
+| `crates/disktree-app/src/views.rs` | the screens |
+| `crates/disktree-app/src/treemap_view.rs` | painting the mosaic and its labels |
+| `crates/disktree-app/src/ui.rs` | the spacing, type and size scale, in `rem` |
+| `crates/disktree-app/src/tests.rs` | end-to-end tests through a real window |
+| `packaging/`, `assets/`, `Makefile` | the desktop entry, the icon, and install |
+
+The interface follows the
+[GPUI Kit design guides](https://gpui-kit.com/versions/main/docs/design-guides/):
+every size is on one `rem` scale so interface zoom keeps its proportions,
+primary is reserved for what Enter does, and the only question the app asks is
+the one it cannot take back.
+
+## License
+
+MIT