# i-am-gcroot List, filter and delete Nix garbage collector roots from a TUI, an optional web UI, or the command line. ``` nix run github:illustris/i-am-gcroot # TUI nix run . -- --web # TUI + web UI on 127.0.0.1:8377 nix run . -- list -q 'under:/tmp older:7d' --sizes ``` ## What it finds | Kind | What it is | Delete does | |---|---|---| | `indirect` | a link outside the gcroots tree (`./result`, `.gcroots/foo`) registered via `/nix/var/nix/gcroots/auto` | removes the link (and the `auto/` entry if writable; `nix-store --gc` prunes it otherwise) | | `dangling` | an `auto/` entry whose link is already gone | removes the `auto/` entry (needs root) | | `profile` | a profile generation, `--link`, system or user | `nix-env --profile

--delete-generations N` | | `direct` | any other symlink in `/nix/var/nix/gcroots` | removes the link | | `runtime` | store paths held by running processes (`/proc/...`), grouped per PID | never deletable; hidden unless asked for | Protected roots (marked `!`) are refused unless `--force` is given: the current generation of every profile, and `gcroots/current-system` / `gcroots/booted-system`. Only symlinks are ever removed. Nothing in `/nix/store` is touched until you run GC: either a full `nix-store --gc` (`g` in the TUI, the "run gc" button, `i-am-gcroot gc`) or a targeted collect right after deleting (`X` in the TUI, "delete + collect", `rm -c`). Targeted collect takes the closures of the roots just deleted, subtracts everything still reachable from any GC root (including runtime roots), and runs `nix-store --delete` on the rest. Nix re-checks liveness itself, so a path that turns out to be alive (for example through `keep-derivations`) is kept and reported. It takes tens of seconds rather than a walk of the whole store. Roots that nix creates for its own caches (anything under `.cache/nix/`, like `~/.cache/nix/flake-registry.json`) are hidden by default. Show them with `h` in the TUI, the "hidden" checkbox, `--all`, or the `is:hidden` query term. Closure sizes come from `nix path-info -S` and load in the background. The "up to" figure for a selection is the sum of closures; shared paths may stay alive through other roots, so the real amount freed is usually less. ## Filter syntax Terms are whitespace separated and ANDed. Prefix any term with `-` to negate it. | Term | Matches | |---|---| | `foo` | case-insensitive substring of link, target, via or command | | `/re/` | regex over the same fields (no spaces, use `\s`; terms with more than two `/` are substrings) | | `kind:indirect,dangling` | kinds (prefixes like `kind:prof` work) | | `owner:me`, `owner:alice`, `owner:1000` | owner of the link | | `under:/tmp/claude-` | link starts with this prefix | | `older:30d`, `newer:2h` | link mtime (`s m h d w y`) | | `size>1G`, `size<10M` | closure size (`K M G T`) | | `is:protected`, `is:current`, `is:dangling`, `is:hidden` | flags (`is:hidden` also makes hidden roots visible) | ## TUI keys | Key | Action | |---|---| | `j/k`, arrows, `pgup/pgdn`, `home/end` | move | | `space` / `x` | mark / unmark | | `a` / `A` | mark all shown (non-protected) / clear marks | | `d` | delete marked roots (or the one under the cursor), with confirmation | | `X` | delete, then garbage collect only the store paths those roots kept alive | | `D` | dry run | | `g` | run `nix-store --gc` | | `/` | edit filter (`enter`/`esc` to leave, `esc` again clears it) | | `1`-`5`, `0` | toggle kinds, reset kinds | | `h` | show/hide nix cache roots | | `s` / `S` | cycle sort key (age, size, target, kind, link) / reverse | | `enter` | details | | `R` | full results of the last delete or dry run | | `r` | rescan | | `?` | help | Below the key hints, an activity line shows the running operation with a timer, then a one-line outcome (failures included); `R` shows the per-root details. The list is rescanned from disk after every delete. ## CLI ``` i-am-gcroot [tui] [-q QUERY] [--web] [--addr ADDR] [--no-auth] [--runtime] [--force] i-am-gcroot list [-q QUERY] [--kind K,..] [--sort KEY] [--desc] [--sizes] [--json] [--runtime] [--all] i-am-gcroot rm [-n] [-y] [-c] [--force] [--all] (-q QUERY | LINK...) i-am-gcroot gc i-am-gcroot web [--addr ADDR] [--no-auth] [--force] [--runtime] ``` `rm` asks for confirmation unless `-y`; `-n` is a dry run; `-c` runs the targeted collect afterwards; `--all` lets `-q` match hidden roots (explicit link arguments always work). ## Web UI `i-am-gcroot web` (headless) or `--web` alongside the TUI. It binds to `127.0.0.1:8377` and generates a random token at startup; open the printed URL (`?token=...`), which sets a cookie. POST requests additionally require the token in an `X-Token` or `Authorization: Bearer` header (the page sends it), so a cross-site form cannot trigger deletes. `--no-auth` disables this; only use it on a trusted socket. JSON API (with `Authorization: Bearer `): - `GET /api/roots?q=...&kind=indirect&kind=profile&sort=size&desc=1&hidden=1` - `POST /api/delete` with `{"links": ["/home/me/result"], "dryRun": false, "collect": true}`, returns `{"results": [...], "collected": {...}}` - `POST /api/gc` ## Permissions Run as your user to manage your own roots. Root-owned roots (system profile generations, `auto/` entries of dangling roots, other users' links) fail with a hint to rerun under `sudo`. Runtime roots of other users' processes show as `{censored}` unless run as root. ## NixOS ```nix { inputs.i-am-gcroot.url = "github:illustris/i-am-gcroot"; # ... imports = [ inputs.i-am-gcroot.nixosModules.default ]; programs.i-am-gcroot.enable = true; } ```