voom 0.14.1

Fast, safe, parallel build-artifact pruning across every major language ecosystem
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
<!-- markdownlint-disable MD033 MD041 -->
<div align="center">

<img src="assets/banner.svg" alt="voom — clean up the pink snow" width="820">

<em>
Then the Voom&hellip;<br>
It went VOOM!<br>
And, oh boy!<br>
What a VOOM!<br>
<br>
Now, don't ask me what Voom is.<br>
I never will know.<br>
But, boy!<br>
Let me tell you it does clean up snow!
</em>

<sub>Dr. Seuss, <em>The Cat in the Hat Comes Back</em></sub>

**Reclaim every build artifact on your disk in one parallel pass — and prove each one before deleting it.**

voom finds and removes build output anywhere in a tree: `target/`, `dist/`, `__pycache__/`,
`.gradle/`, `.zig-cache/` and the rest. A directory counts as an artifact only when a marker file
proves its ecosystem, so a hand-written `bin/` or `vendor/` is never taken.

Every major ecosystem · marker-anchored classification · six deletion rails · a dry run that is the
real pipeline · hierarchical TOML · a named tool-cache catalog · watch mode · git hooks

[![crates.io](https://img.shields.io/crates/v/voom?style=flat-square&color=007ec6)](https://crates.io/crates/voom)
[![npm](https://img.shields.io/npm/v/@goldziher/voom?style=flat-square&color=007ec6&label=npm)](https://www.npmjs.com/package/@goldziher/voom)
[![PyPI](https://img.shields.io/pypi/v/voom-cli?style=flat-square&color=007ec6)](https://pypi.org/project/voom-cli/)
[![CI](https://img.shields.io/github/actions/workflow/status/Goldziher/voom/ci.yml?style=flat-square&color=007ec6&label=CI)](https://github.com/Goldziher/voom/actions)
[![license: MIT](https://img.shields.io/badge/license-MIT-007ec6?style=flat-square)](./LICENSE)
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-007ec6?style=flat-square&logo=github-sponsors)](https://github.com/sponsors/Goldziher)

[Install](#installation)&nbsp;·&nbsp;[Usage](#usage)&nbsp;·&nbsp;[Safety](#safety)&nbsp;·&nbsp;[Caches](#cache-catalog)&nbsp;·&nbsp;[Suggest](#finding-what-the-catalog-does-not-cover)&nbsp;·&nbsp;[Ecosystems](#supported-ecosystems)&nbsp;·&nbsp;[Configuration](#configuration)&nbsp;·&nbsp;[Git hooks](#git-hooks)&nbsp;·&nbsp;[Reference](docs/reference.md)

</div>

---

<!-- markdownlint-disable MD013 -->
<p align="center"><img src="assets/demo.gif" alt="voom previewing a tree with --dry-run, running the same sweep for real with identical results, and leaving a target directory that no Cargo.toml proved" width="820"></p>
<p align="center"><em>A <code>--dry-run</code>, then the same sweep for real: identical to the byte, because the dry run is the same pipeline with the last step withheld. A symlinked <code>target/</code> is refused rather than followed — and the <code>target/</code> that no <code>Cargo.toml</code> proved is still there afterwards.</em></p>
<!-- markdownlint-enable MD013 -->

---

## Installation

| Channel | Command |
| ------- | ------- |
| Homebrew (macOS/Linux) | `brew install goldziher/tap/voom` |
| Cargo (Rust) | `cargo install voom` |
| npm (Node.js) | `pnpm add -g @goldziher/voom` |
| pip (Python) | `pip install voom-cli` |

The binary is called `voom` however you install it. The package names differ because `voom` was
already taken on npm and PyPI — see [ADR 0010](adrs/0010-distribution-and-naming.md).

Prefer prebuilt binaries? [`cargo binstall voom`](https://github.com/cargo-bins/cargo-binstall)
downloads a release archive instead of compiling from source.

Run without installing:

```bash
pnpm dlx @goldziher/voom@latest --dry-run ~
uvx --from voom-cli voom --dry-run ~
```

<details>
<summary><b>Build from source</b></summary>

```bash
git clone https://github.com/Goldziher/voom.git
cd voom
cargo install --path .
```

Requires Rust 1.88+ (edition 2024).

</details>

## Quick start

```bash
voom --dry-run ~      # see what's reclaimable across everything, without touching anything
voom ~                # actually clean it up — no confirmation prompt, see Safety
voom ./my-project     # clean one project
```

What a run prints:

```text
/projects
  removed   4.20 GB  rust  api/target
  refused       0 B  rust  link/target    — is a symlink
  removed  18.50 MB  node  web/dist

2 artifacts, 4.22 GB reclaimed in 1.23s
  scan 900.00ms · policy 12.00ms · size 210.00ms · delete 98.00ms
  rust 4.20 GB (1), node 18.50 MB (1)
  1 artifact refused by a safety rail
```

## Usage

Start narrow: `voom --dry-run --verbose ~/projects`, and read the skips before widening to `~`.
With no path, voom scans `.`. Pass `~ /tmp` explicitly to cover home-directory caches. Relocated
build output whose name no catalog entry knows — a `CARGO_TARGET_DIR` pointed at `/tmp` — also
needs `--clean-tagged`, which is the only proof that does not depend on a name.

```bash
voom --dry-run --verbose ~                                  # preview, with a reason for every skip
voom --min-age 7d ~                                          # only artifacts untouched for a week
voom --ecosystem rust --ecosystem node ~                     # only these ecosystems
voom --format json ~ | jq '.totals'                          # machine-readable
voom --list-caches                                           # the tool caches this machine holds
voom --dry-run --clear-caches ~ /tmp                         # preview tool caches and tagged build output
voom --dry-run --aggressive ~ /tmp                          # all supported cleanup, including worktree edits
voom --dry-run --clean-caches=cargo-registry,uv ~            # remove these named tool caches
voom --dry-run --include .mytool-cache ~/projects            # sweep something the catalog misses
voom --dry-run --clean-dependencies ~                        # also node_modules/, vendor/, deps/, .venv/
voom --no-git ~                                               # skip the git housekeeping a sweep does
voom --summary --config ./ci-voom.toml ~/projects             # totals only, explicit config file
```

Run `voom --help` for the full, grouped list, or see the
[options reference](docs/reference.md#options).

Exit codes: `0` clean, `1` some artifacts could not be removed (a partial removal counts), `2`
usage or config error, `3` findings with `--dry-run --exit-code` (for hooks). Git housekeeping
never fails a sweep. `catalog`, `--list-caches`, `config show` and `suggest` always exit `0`.

### Options

Every flag and subcommand, with defaults and short forms, is in the
[reference](docs/reference.md#options). `voom --help` prints the same list grouped the same way.

## Safety

voom deletes by default, with no confirmation prompt. Safety comes from these rules:

**1. Nothing is removed without a marker file proving its ecosystem.** `target/` is only Rust's
build output when a `Cargo.toml` sits beside it; `obj/` is only .NET's when a project file —
`*.csproj`, `*.fsproj`, `*.vbproj` or `*.sln` — sits at most three directories above it. A marker's
position relative to the candidate is one of three anchors: `Sibling` (beside the artifact, most
ecosystems), `Ancestor(n)` (up to `n` directories above, for artifacts nested inside a project),
or `Inside` (the marker is written *inside* the candidate itself — `~/.cargo/registry`'s
`CACHEDIR.TAG`, `.basemind/`'s `agent-id`). `--verbose` says which marker was missing.

**2. Dependency directories are off by default.** `node_modules/`, `vendor/` (Rust, PHP composer,
Go), mix's `deps/` and Python's `.venv/` are network-fetched caches, not build output — removing
one costs a re-download and can break offline work. `--clean-dependencies` turns the group on and
`--enable <spec>` turns on exactly one; a marker still has to prove each.

**3. Tool caches and installed toolchains are skipped by location**, not name — an installed pnpm
sits beside a real `package.json` and is otherwise indistinguishable from a project someone built.
The skip is unconditional: nothing re-opens those locations, though naming one of those paths as
a scan root sweeps it anyway, because root intent outranks a walk heuristic.

**4. Six rails you cannot switch off.** Symlinks and Windows reparse points are refused rather than
followed. Every target is canonicalized. An append-only denylist protects `/`, `$HOME` itself,
`/usr`, `/System`, `.git` and friends. The result must resolve strictly below a scan root.
Filesystem boundaries are not crossed (`--one-file-system=false` to opt out). A failure on one
artifact is reported and isolated rather than aborting the run.

**5. Nothing a repository tracks is removed.** A marker proves an ecosystem, not that nobody
committed the directory beside it: a checked-in `dist/` is shaped exactly like a build's. Before
anything the walk inferred is removed, the repository's index is asked whether it tracks a file
inside, and if it does the artifact is refused — `holds files git tracks`. An `include` names a
path outright and is not asked.

**6. `--dry-run` is the real pipeline with the last step withheld**, not a simulation.

### Detached removal

A real run does not unlink anything while you wait. Once every rail has passed, each artifact is
renamed into voom's trash — `voom/trash` in the platform cache directory, or `VOOM_TRASH_DIR` —
in one `rename`, whatever it holds, and a background reaper started when the run ends frees the
trash at low priority. The report says `detached` for these, without a size: the reaper counts
the bytes as it frees them, and the next run, or `voom reap`, reports what it freed. An artifact
on another filesystem than the trash, or one the trash sits inside, is removed in place.

```bash
voom ~                # returns once everything is detached
voom reap             # wait for the reaper, free whatever is left, and say what it freed
voom --wait ~         # unlink in place before exiting, as before (also VOOM_WAIT=1)
```

The reaper removes each trash entry through the same rails, rooted at the trash. A crash or a
reboot leaves the trash for the next `voom reap`, or for the reaper the next run starts.

Full reasoning in [ADR 0002](adrs/0002-marker-anchored-classification.md) and
[ADR 0006](adrs/0006-deletion-semantics.md).

## Cache catalog

The ecosystem catalog covers build output; it has nothing to say about `~/.cargo/registry` or
`~/.cache/uv`, which are machine-global downloads rather than anything a project built.
`voom --list-caches` lists the ones voom knows how to empty by name:

| id | Cache | Location(s) |
| --- | --- | --- |
| `cargo-registry` | Cargo registry | `~/.cargo/registry` |
| `cargo-git` | Cargo git checkouts | `~/.cargo/git` |
| `uv` | uv | `~/.cache/uv` |
| `gradle-caches` | Gradle caches | `~/.gradle/caches` |
| `go-build` | Go build cache | `~/Library/Caches/go-build`, `~/.cache/go-build` |
| `go-mod` | Go module cache | `~/go/pkg/mod` |
| `npm` | npm cache | `~/.npm/_cacache` |
| `pnpm` | pnpm metadata cache | `~/Library/Caches/pnpm`, `~/.cache/pnpm` |
| `pnpm-store` | pnpm content-addressable store | `~/Library/pnpm/store`, `~/.local/share/pnpm/store`, `~/.pnpm-store`, `~/AppData/Local/pnpm/store` |
| `pip` | pip cache | `~/Library/Caches/pip`, `~/.cache/pip`, `~/AppData/Local/pip/Cache` |
| `homebrew` | Homebrew downloads | `~/Library/Caches/Homebrew`, `~/.cache/Homebrew` |
| `prek` | prek cache | `~/.cache/prek` |
| `pre-commit` | pre-commit cache | `~/.cache/pre-commit` |
| `ms-playwright` | Playwright browsers | `~/Library/Caches/ms-playwright`, `~/.cache/ms-playwright`, `~/AppData/Local/ms-playwright` |
| `node-gyp` | node-gyp headers | `~/Library/Caches/node-gyp`, `~/.cache/node-gyp`, `~/AppData/Local/node-gyp/Cache` |
| `golangci-lint` | golangci-lint cache | `~/Library/Caches/golangci-lint`, `~/.cache/golangci-lint`, `~/AppData/Local/golangci-lint` |
| `tree-sitter-language-pack` | tree-sitter language pack | `~/Library/Caches/tree-sitter-language-pack`, `~/.cache/tree-sitter-language-pack` |
| `huggingface` | Hugging Face hub | `~/.cache/huggingface/hub` |
| `pub` | Dart pub cache | `~/.pub-cache` |
| `deno` | Deno cache | `~/Library/Caches/deno`, `~/.cache/deno`, `~/.deno` |
| `poly` | poly cache | `~/.cache/poly`, `~/Library/Caches/poly`, `~/AppData/Local/poly` |
| `alef-global` | alef global cache | `~/.cache/alef` |
| `codex-cache` | Codex app cache | `~/.codex/cache` |
| `codex-scratch` | Codex scratch directories | `~/.codex/.tmp` |

The id is what `--clean-caches` and `[caches] enable` take — not always the tool's name, since a
cache id and an ecosystem id sharing one word would leave a report unable to say which table a
line came from. Each is proven the way everything else is: not by its path, but by a marker the
tool wrote *inside* it, most often the cross-tool [`CACHEDIR.TAG`](https://bford.info/cachedir/).
None is ever removed without that marker, and unless it lies under the tree being swept:

```bash
voom --list-caches                      # the caches on this machine (instant)
voom --list-caches --sizes              # ... each measured, which walks every one of them
voom --list-caches --verbose            # ... and every location, marker and note the table knows
voom --dry-run --clean-caches ~ /tmp    # named caches plus signature-verified tagged build output
voom --dry-run --clear-caches ~ /tmp    # the same flag, spelled that way
voom --dry-run --clean-caches=uv,go-build ~   # or the ones you name, comma-separated with `=`
```

A bare `--clean-caches` (alias `--clear-caches`), or `--clean-caches=all`, also enables
`--clean-tagged` to reach relocated build caches. Named IDs such as `uv,go-build` remain scoped
to those caches. `[caches] enable = ["all"]` supplies the same tagged default in user or explicit
configuration, unless `[tagged] enabled = false` overrides it; the full CLI flag overrides that
configuration. Cache clearing alone does not imply worktree removal; `--aggressive` does.

By default `--list-caches` prints only the cache locations that actually exist here, each with
its path, without measuring anything; `--sizes` adds how much disk each holds (tens of gigabytes
take as long to count as to list), and `--verbose` shows the whole table — every location the
table knows about, whether it is present here, and the marker that would prove it.

`huggingface` is the one entry a bare `--clean-caches` leaves alone: models are gigabytes, some
gated or withdrawn, so it is removed only by naming it. `pnpm-store` is safe to remove — projects
hold hard links into it — but the next install of anything not yet linked downloads it again.
Browsers (Chrome, puppeteer's) and JetBrains' system directories are absent for lack of a marker
their tools write; JetBrains' also holds Local History.

For an ordinary removal with no size-based keep policy, voom counts reclaimed bytes while
unlinking instead of walking the cache once to measure it and again to delete it. Dry runs and
size-based policies still need a measurement pass. Flat directories use bounded batches of
parallel unlinks. Reported MB/s includes per-file filesystem and security checks: a cache of
thousands of tiny files can have much lower byte throughput than one containing large files.

A cache whose contents are only shard directories — sccache, zig, NuGet, Maven — is deliberately
absent: the marker would prove nothing the path had not already said. See
[ADR 0012](adrs/0012-cache-catalog.md).

## Tagged directories

A catalog entry matches a *name* and a cache entry matches a *location*. Neither can reach a build
directory that has neither — a `CARGO_TARGET_DIR` pointed at `/tmp`, a `.build-cache/` somebody
renamed, a cache belonging to a tool voom has never heard of. Measured on one workstation, that was
104 GB across 53 directories.

`--clean-tagged`, also included in a full `--clear-caches`, reaches them using the one piece of
evidence that needs no name and no location: the [`CACHEDIR.TAG`](https://bford.info/cachedir/) the tool wrote *inside* the directory to say the
contents can be rebuilt. `tar --exclude-caching`, `rsync --exclude-tag`, Borg and restic all honour
the same file.

```bash
voom --dry-run --clean-tagged ~ /tmp   # read it first; this takes directories of any name
```

It is never on by default, and the reasons it is safe anyway are worth stating:

- **The signature is verified**, not the filename. A file someone happened to call `CACHEDIR.TAG`
  does not license a removal.
- **An anchored artifact wins** where both apply, so `target/` beside a `Cargo.toml` is still
  reported as Rust's.
- **A tagged directory is pruned, not descended** — which makes a sweep *faster*, since a relocated
  target directory is otherwise walked in full to report nothing.
- **A symlink is never probed**, because reading through it is the one thing voom does not do.
- Every keep policy, the protected denylist, containment and the filesystem boundary are unchanged.

Also settable as `[tagged] enabled = true` in a `voom.toml`, which is the useful form for a single
project whose output goes somewhere the catalog cannot name. See
[ADR 0013](adrs/0013-tagged-directories.md).

## Finding what the catalog does not cover

The catalog covers ecosystems, not the cache your own tooling writes into every package
directory. `include` ([ADR 0004](adrs/0004-configuration.md)) is the answer, but you have to know
the directory's name to write the line. `voom suggest` walks a tree and reports the repeated
directories git already ignores where they sit, ranked by size, with the line that would sweep
each:

```console
$ voom suggest ~/projects
     42.70 GB  .alef  across 69 directories
      3.00 GB  .basemind  across 13 directories

Add to voom.toml what you recognise:

  include = [".alef"]
  include = [".basemind"]

Read the list before pasting it. A .gitignore also lists local configuration and
scratch data, which is why voom suggests rather than sweeps.
```

It removes nothing. `--include <GLOB>` is the command-line equivalent of `voom.toml`'s `include`
key, for when you already know the name.

## Supported ecosystems

| Ecosystem | Marker | Artifacts |
| --- | --- | --- |
| Rust | `Cargo.toml` | `target/`, `vendor/`† |
| Node / TypeScript | `package.json` | `dist/`, `.next/`, `.nuxt/`, `.svelte-kit/`, `.astro/`, `.turbo/`, `.parcel-cache/`, `.vite/`, `.nyc_output/`, `*.tsbuildinfo`, `build/`†, `node_modules/`† |
| Python | `pyproject.toml`, `setup.py`, `setup.cfg` | `__pycache__/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `*.egg-info/`, `htmlcov/`, `.coverage`, `dist/`, `.tox/`†, `build/`†, `.venv/`† |
| Go | `go.mod` | `bin/`†, `vendor/`† |
| Zig | `build.zig` | `.zig-cache/`, `zig-cache/`, `zig-out/` |
| Swift | `Package.swift` | `.build/` |
| Xcode | `*.xcodeproj`, `*.xcworkspace` | `DerivedData/` |
| Maven | `pom.xml` | `target/` |
| Gradle / Kotlin | `build.gradle`, `build.gradle.kts`, `settings.gradle*` | `build/`, `.gradle/` |
| .NET | `*.csproj`, `*.fsproj`, `*.vbproj`, `*.sln` | `bin/`, `obj/` |
| CMake / C++ | `CMakeLists.txt` | `cmake-build-*/`, `CMakeFiles/`, `build/`† |
| Dart / Flutter | `pubspec.yaml` | `.dart_tool/`, `build/` |
| Elixir | `mix.exs` | `_build/`, `.elixir_ls/`, `deps/`† |
| Ruby | `Gemfile`, `*.gemspec` | `coverage/`, `vendor/bundle/`†, `pkg/`†, `tmp/`† |
| PHP | `composer.json` | `.phpunit.cache/`, `.phpunit.result.cache`, `vendor/`† |
| Scala / sbt | `build.sbt` | `target/`, `project/target/`, `.bloop/`, `.metals/` |
| Haskell | `*.cabal`, `stack.yaml` | `dist-newstyle/`, `.stack-work/` |
| OCaml / dune | `dune-project` | `_build/` |
| Julia | `Project.toml` | `deps/build/`† |
| R | `DESCRIPTION` | `*.Rcheck/`, `src/*.o`, `src/*.so` |
| Nim | `*.nimble` | `nimcache/` |
| Elm | `elm.json` | `elm-stuff/` |
| Terraform | `*.tf` | `.terraform/` |
| Bazel | `WORKSPACE`, `WORKSPACE.bazel`, `MODULE.bazel` | `bazel-bin/`, `bazel-out/`, `bazel-testlogs/`, `__pycache__/`§, `.pytest_cache/`§, `.mypy_cache/`§, `.ruff_cache/`§ |
| alef | `CACHEDIR.TAG` | `.alef/`‡ |
| basemind | `agent-id` | `.basemind/`†‡ |

‡ Proven from *inside*: `agent-id` is the file basemind writes into `.basemind/` when it
creates the index, so the directory declares itself rather than relying on a sibling config
that is usually absent. Every other row looks for its marker beside or above the artifact.
A tool that wants its caches swept can do the same with the cross-tool
[`CACHEDIR.TAG`](https://bford.info/cachedir/).

§ Proven by a `WORKSPACE`/`WORKSPACE.bazel`/`MODULE.bazel` anywhere above, with no level bound
— these four are Python's own artifacts, declared a second time here for the tree that has no
Python manifest anywhere near them. The Python row's `Ancestor(1)` still proves the common case
faster; this is what reaches the rest. See
[ADR 0002](adrs/0002-marker-anchored-classification.md)'s `Anchor::WorkspaceRoot` amendment.

† Off by default — the name is also a plausible source directory in that ecosystem, or removal is
expensive rather than cheap. Turn one on for a single run with `--enable python.venv`, or per
ecosystem and per path in your config. `voom catalog` prints the live table, with the reason each
`†` entry needs an opt-in.

## Configuration

voom merges built-in defaults, `~/.config/voom/config.toml`, and every `voom.toml` from the scan
root down to each candidate — nearest wins, so a repository can protect its own quirks and still
be swept correctly from `$HOME`. Every table rejects unknown fields, so a typo is a hard load
error rather than a guard that silently never took effect.

```toml
exclude = ["~/work/client-x/**"]   # never scanned, always wins
include = ["~/scratch/build-junk"] # swept without a marker — explicit intent

[keep]
min_age = "7d"                     # never remove something modified more recently
```

`[caches]`, `[bazel]` and `[docker]` drive removal outside the swept tree, so they are read only from
`~/.config/voom/config.toml` or an explicit `--config`, never from a repository's `voom.toml`; a
repository that sets one is a hard error rather than a silent no-op.

Keep policies, per-ecosystem and per-path overrides, `[ecosystems]`, `[git]`, `[bazel]`, `[docker]` and the Windows
quoting rule are in the [configuration reference](docs/configuration.md).
`voom config show [PATH]` prints the merged result and the files it came from.

## JSON output

`--format json` writes one object per run to stdout; diagnostics stay on stderr. It implies
`--verbose` and suppresses the spinner. The shape is versioned and documented field by field in
the [reference](docs/reference.md#json-output).

```bash
voom --dry-run --format json ~ | jq '.totals'
```

## Git housekeeping

An ordinary sweep also runs git's own local housekeeping in every repository it walks past —
free, since the walker already meets `.git` on its way past:

| Step | What it does |
| --- | --- |
| `git worktree prune --expire` | drops the administration of worktrees whose checkout has been gone for three months |
| `git gc --auto` | repacks **only if** git's own thresholds say it is worth it |

Neither contacts a network or expires a reflog beyond git's own policy, and voom never passes
`--prune=now`, `--aggressive`, or `git reflog expire`. Hooks are disabled for every invocation. An
in-progress rebase, merge, cherry-pick or bisect is skipped, and a linked worktree is resolved to
its object store and pruned once rather than per checkout. The report says nothing when nothing
was found:

```text
  pruned  api  — 2 stale worktrees pruned
```

Turn it off with `--no-git`, or `[git] enabled = false` in a `voom.toml` (the flag wins). See
[ADR 0011](adrs/0011-git-housekeeping.md).

`voom git-prune` runs the same housekeeping on its own. `--remotes` drops remote-tracking
branches whose upstream is gone — one round trip per remote per repository, which hangs without
connectivity and can block on a credential prompt, so it is deliberately not part of an ordinary
sweep:

```bash
voom git-prune -n ~/projects              # what would be pruned
voom git-prune --remotes ~/projects       # also drop remote-tracking branches whose upstream is gone
voom git-prune --format json ~/projects   # machine-readable, same shape embedded under a sweep's "git" key
```

A repository whose housekeeping fails or times out makes `git-prune` exit `1`; a skip is a rail
doing its job and exits `0`.

## Merged worktrees

A worktree checked out for a ticket and left after the merge keeps a full checkout — and a Bazel
output base — on disk. `--remove-merged-worktrees` (on a sweep, or on `voom git-prune`) removes
the ones whose work is already merged:

```bash
voom -n --remove-merged-worktrees ~/code          # what would go
voom --remove-merged-worktrees ~/code             # remove them; Bazel orphans go in the same run
voom --remove-merged-worktrees --stale-worktrees 30d ~/code   # and unmerged ones idle for 30 days
voom -n --remove-merged-worktrees --github-merged-worktrees ~ /tmp   # also prove squash/rebase merges
```

Ordinarily a worktree is removed only when its `HEAD` is an ancestor of the default branch (the local
`origin/HEAD`, else `main`/`master` — voom never fetches, so a stale ref errs toward keeping),
it is not locked or the current directory, it is stored under a path you asked voom to sweep (one
elsewhere on disk is reported and kept), and its working tree holds nothing but deleted tracked
build output (a `dist/`, `target/`, `node_modules/` or `__pycache__/` at any depth, a top-level
`build/` or `out/`) and ignored build-output trees such as `target/`. Ignored Elixir `deps/`
also qualifies beside a real `mix.exs`, and Python `.venv/` beside a real `pyproject.toml`,
`setup.py` or `setup.cfg`. These dependency candidates must be actual directories, not symlinks,
and their sibling markers must be regular files, not symlinks; without that proof they keep the
worktree as local changes. Any modified, staged or untracked path, or other ignored content
such as a `.env` or local database, is reported as merged-with-local-changes and kept. Branches are never deleted. It is off by
default and cannot be turned on from `voom.toml`, because unlike the rest of git housekeeping it
can lose work. `--clear-caches` alone does not imply it; `--aggressive` does.

For squash or rebase merges, add `--github-merged-worktrees` with
`--remove-merged-worktrees` on a sweep or `git-prune`. It opts into network access through
`gh api --hostname github.com` and accepts a merged pull request only when its head SHA exactly
matches the worktree HEAD and its base repository matches `origin`. Any base branch qualifies,
including release and integration branches. Missing authentication, network/API errors, unsupported
remotes, and mismatched SHAs provide no merge proof; local ancestry remains the ordinary offline
proof. All working-tree and containment checks still apply. Before any GitHub-proven HEAD
is removed without local ancestry proof, voom retains it at `refs/voom/merged-worktrees/<SHA>`;
a dry run writes no ref. Ignored evidence keeps the checkout, and voom neither archives that
evidence nor force-removes submodule worktrees.

`--stale-worktrees <DURATION>` widens that to unmerged worktrees that have gone quiet: nothing
committed, checked out or rebased for the given time, some ref still reaching their `HEAD` (the
branch is kept; a detached `HEAD` nothing else reaches is never removed), and the same
working-tree rule as above. See [ADR 0016](adrs/0016-merged-worktree-removal.md).

## Aggressive cleanup

`--aggressive` enables every catalog artifact, including `node_modules/`, `.venv/`, `vendor/`
and other opt-in dependency directories; every supported cache, including Hugging Face models;
tagged-directory cleanup; permission repair (`--force`); worktree removal; and unused Docker
images and build cache. Docker has no minimum age in this mode unless `--docker-max-age` sets
one. Volumes still require `--docker-volumes` or `--docker-volumes-all`; containers are never
removed. Artifact disables, excludes and keep policies continue to govern artifacts and caches. Markers and deletion guards still have to prove each
artifact and cache.

It discards modified, staged, untracked and ignored files in eligible worktrees without creating
a recovery archive. Merged and unmerged worktrees qualify, with no minimum idle age unless
`--stale-worktrees` supplies one. Branches remain in the repository. A detached HEAD that no
other ref reaches is retained at `refs/voom/aggressive-worktrees/<SHA>` before removal; failure
to retain it keeps the checkout, and dry-run writes no ref. Local checkout contents are
permanently lost. No GitHub
lookup occurs unless `--github-merged-worktrees` is also given.

```bash
voom -n --aggressive ~ /tmp
voom --aggressive ~ /tmp
voom --aggressive --stale-worktrees 30d ~/code
```

Aggressive cleanup also removes dangling checkouts whose `.git` file points at missing worktree
administration. Their lost HEAD and index make merge and local-change checks impossible;
`--aggressive` explicitly accepts that loss of evidence. Without it they are reported and kept.
Main checkouts, locked worktrees, the current working directory and paths outside the supplied
roots remain protected. Git still refuses force-removal of worktrees containing submodules.
The deletion safety rails still apply. See
[ADR 0018](adrs/0018-aggressive-cleanup.md).

An untagged custom Cargo target directory still needs an explicit `--include` after verifying
that its whole contents are disposable. Cargo-shaped files alone do not prove that a directory
contains only build output:

```bash
voom -n --aggressive --include .my-cargo-target ~/projects
```

## Bazel output-base housekeeping

Every workspace path that has run Bazel gets its own output base, and nothing removes it when
the workspace goes away — not `git worktree prune`, which never sees it, and not the cache
catalog above, which proves one fixed location rather than one of however many a user has
pointed Bazel at. Bazel writes `DO_NOT_BUILD_HERE` into an output base's root naming the
workspace that owns it, and that is proof enough to answer the one question that matters: is
the owner still there?

```bash
voom ~/code                      # a sweep prunes Bazel too
voom -n ~/code                   # what would be removed, without removing it
voom --bazel-max-age 14d ~/code  # treat a base as stale after two weeks, not one
voom --no-bazel ~/code           # leave Bazel alone
voom --clear-caches=bazel        # clear Bazel completely, stopping servers first
```

It searches `/tmp/_bazel_<user>`, `/var/tmp/_bazel_<user>`,
`~/.cache/bazel/_bazel_<user>` and `~/Library/Caches/bazel/_bazel_<user>` (or the
`VOOM_BAZEL_ROOTS` path list, which replaces them), and finds nothing at whichever do not exist
on this machine — that absence is never a usage error. An output base is removed when:

- its recorded owner no longer exists on disk;
- its owner is a git worktree whose administration is gone (`git worktree remove` ran, the
  directory survived);
- nothing has built there for longer than `--bazel-max-age` (default `7d`) — the stale worktrees a
  monorepo accumulates, one output base each.

Removing a base also unlinks the owner's dangling `bazel-*` convenience symlinks. A base with a
running server is never touched. Install bases no surviving output base points at, and files in
the shared download cache not used within the age limit, go the same way.

The housekeeping runs beside the sweep, over the conventional roots, fanned out across the same
worker pool, and says nothing when there is nothing to do; `--no-bazel` skips it and
`--bazel-max-age` sets the age. `--clear-caches` is the exception to age: it clears Bazel completely — every output base,
install base and cached download, live workspaces included, after stopping their servers. The
next build starts cold. See [ADR 0014](adrs/0014-bazel-output-base-housekeeping.md).

## Docker housekeeping

Docker keeps images, build cache and volumes until told otherwise, and on macOS and Windows keeps
them inside a VM whose disk image on the host **never shrinks by itself**: a prune frees space in
the guest, and the host gets it back only when `fstrim` runs there. voom does both.

```bash
voom docker-prune -n                          # what would go, and what the VM trim would start from
voom docker-prune                             # prune, trim the VM, report the host bytes returned
voom docker-prune --max-age 14d               # images and cache unused for two weeks, not one
voom docker-prune --volumes                   # also anonymous volumes no container mounts
voom -n --docker ~/code                       # a sweep that prunes Docker beside the artifacts
```

Off in a sweep unless `--docker` (or `[docker] enabled = true`) asks, because it talks to a
daemon. What it removes:

- **dangling images**, and **images no container was made from** that are older than the age
  (`7d`, `--max-age` / `--docker-max-age`, mapped to Docker's `until=` in whole hours);
- **build cache** nothing has read for that long;
- with `--volumes` (`--docker-volumes` in a sweep), **anonymous volumes** no container mounts;
  `--volumes-all` also takes named ones, which is data loss if one held a database you wanted.

It never removes a container, and never an image or volume a container — running or stopped —
refers to. A dry run is the same plan with the commands withheld; the real run reports the bytes
Docker itself printed.

After a real run on Colima, Lima, Rancher Desktop or a podman machine, voom runs `fstrim` in the VM
and reports how much the host disk image shrank (`st_blocks` before and after). Docker Desktop and
OrbStack trim for themselves, a native Linux daemon has no VM, and an unrecognised endpoint is left
alone. `--no-trim` skips it. A missing `docker`, a stopped daemon or a refused socket is one line
and exit `0`, never a failed sweep. See [ADR 0017](adrs/0017-docker-housekeeping.md).

## Claude Code job scratch

`~/.claude/jobs/<id>/tmp/` is free-form scratch a background job writes to, and nothing reaps
it once the job is done. Nothing on disk says reliably whether a job is done, though — a
`state.json` that says "stopped" can lag a job resumed later outside its own daemon by more
than a week, which is exactly what motivated this command's caution.

```bash
voom claude-prune                     # report only — every job found, nothing removed
voom claude-prune --remove            # actually reclaim eligible jobs' scratch
voom claude-prune --remove -n         # what --remove would do, without doing it
voom claude-prune --min-age 30d       # a longer quiet period than the 14-day default
```

A job is eligible only when **all** hold: no process on this machine right now has its
recorded session on its command line, it has been quiet longer than `--min-age` (14 days by
default), and `--remove` was given. `voom claude-prune` with no flags at all only ever reports
— read what it found, and decide. Only `tmp/` is ever removed; `state.json` and a job's own
record survive. See [ADR 0015](adrs/0015-claude-code-job-scratch.md).

## Watch mode

```bash
voom watch ~/projects
```

Prunes continuously as you work. Filesystem events are coalesced over a debounce window
(`--debounce`, default `5s`), and an artifact is only removed once its subtree has been idle for a
quiet period (`--quiet-period`, default `60s`), so an in-progress build is never touched. Watch
mode never forces. See [ADR 0008](adrs/0008-watch-mode.md).

## Git hooks

The reporting hook is the one to start with — it fails the commit on findings but deletes nothing.

**pre-commit**

```yaml
repos:
  - repo: https://github.com/Goldziher/voom
    rev: v0.4.5
    hooks:
      - id: voom-report      # reports, deletes nothing
      # - id: voom-prune     # actually deletes — opt in deliberately
```

**poly**

```toml
[[hooks.sources]]
id = "voom"
git = "https://github.com/Goldziher/voom.git"
revision = "v0.4.5"
hooks = ["voom-report"]
```

**Lefthook**

```yaml
pre-commit:
  commands:
    voom:
      run: voom --dry-run --report --exit-code .
```

## Performance

voom is I/O-bound, so the wins come from not walking things: it prunes matched artifacts, `.git/`,
dependency directories and tool caches at the directory level rather than descending into them,
and parallelizes sizing and removal separately. Removal is detached (see [Safety](#detached-removal)):
a run renames each artifact into the trash and a background reaper unlinks it, so a sweep that
used to wait an hour and a half on Bazel output bases and package caches returns in seconds.

A git work tree on APFS is walked from its index rather than its directories. A tracked directory
whose link count and modification time agree with what the index lists is clean — it holds
nothing untracked — and costs one `lstat` instead of an `open` and a listing; only directories
with untracked entries are listed. Over 43 linked worktrees of one large repository that took
the scan from 21 s to 6 s. See [ADR 0020](adrs/0020-detached-removal-and-index-guided-walk.md). Removal defaults to a shared pool of eight
workers on Apple platforms and sixteen elsewhere, subject to the file-descriptor limit.
On Apple platforms, directories with fewer than 256 files use one serial batch to avoid
scheduling many tiny tasks; larger flat directories use parallel 64-file batches across the
pool. A long directory prefix does not consume removal's branching budget and serialize the
cache below it. `-j` overrides the removal width and throttles the whole sweep, including the walk.

Compare two release binaries and native `rm` on disposable small-file trees:

```bash
mise run bench -- --before /path/to/baseline --after /path/to/candidate --files 12000 --runs 3
```

The benchmark covers flat, sharded, package-shaped and deeply nested layouts. It creates its
own temporary trees, excludes setup and validation from timing, and emits JSON with raw timings,
files per second and verified byte totals. These warm synthetic fixtures expose regressions;
measure representative copies of real caches with `hyperfine` before making throughput claims.
See [ADR 0005](adrs/0005-traversal-and-parallelism.md) for traversal and
[ADR 0019](adrs/0019-cache-deletion-concurrency.md) for removal concurrency.

## Development

```bash
cargo build
cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --all
poly hooks run pre-commit --all-files      # the authoritative gate
```

Design decisions live in [`adrs/`](./adrs) — start with
[0001](adrs/0001-mission-and-scope.md) and [0002](adrs/0002-marker-anchored-classification.md).
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for adding an ecosystem, which is the most common
contribution and has a checklist.

## Contributing

Issues and pull requests are welcome, especially new ecosystems.

If voom is useful to you, consider [sponsoring development](https://github.com/sponsors/Goldziher).

## License

[MIT](./LICENSE)