Reclaim disk and memory from Bazel

Bazel keeps an output base for every workspace path it has built in, a server for each one recently used, and every archive it has downloaded. None of it is collected: a machine that creates a git worktree per task, as coding agents do, gains an output base per task. Two tasks deal with it:

aspect output-bases shows what is there. It changes nothing.
aspect gc removes what nothing is using.

1. See what is there

aspect output-bases --sort=size

Every output base, grouped by state, largest first: when it was last used, the memory its Bazel server holds, the repository and branch it is checked out on, and its workspace. --sort=size measures sizes, which takes a du of every base; drop it for a listing that returns at once. Two numbers usually matter:

Removable bases: orphaned (the workspace was deleted) and idle (unused for 30 days). The listing ends with their count and size.
Running servers: each holds its memory until it has been idle for Bazel’s --max_idle_secs (3 hours by default). The line under the census gives the total.

2. Preview

aspect gc --dry-run

Lists each base gc would remove and why, the stale download-cache entries, and the total it would free. Nothing is deleted.

  2 Bazel output bases to remove, 3.3 GB:
    2.2 GB  7f18ea0edb2474de1526d9aa847f0ab9  (workspace gone: ~/src/web/.claude/worktrees/feat-search)
    1.1 GB  557089df67d989f705a1cf9794dcb086  (unused for 45d; workspace ~/src/api)
  Bazel download cache: 812 of 2,104 entries unused for 30d or more, 3.1 GB
  would reclaim 6.4 GB; run without --dry-run to remove it

3. Reclaim

aspect gc

Lists the same plan and asks before deleting. A base Bazel uses after the scan is left alone. To remove a base the rules keep, such as an undetermined one, name it:

aspect gc <hash>

4. Tune the rules

To	Run
Keep idle bases longer	`aspect gc --base-max-idle-days=90`
Never remove a base just for being idle	`aspect gc --base-max-idle-days=0`
Remove orphans without the grace period	`aspect gc --orphan-grace-hours=0`
Leave the download cache alone	`aspect gc --download-cache-max-idle-days=0`

The grace period keeps an orphaned base for an hour after its last use, so a worktree torn down and recreated at the same path gets its base back.

5. Run it on a schedule

gc asks before deleting, and refuses off a terminal unless --force says it may. A nightly cron entry on a developer machine:

0 3 * * * aspect gc --force >> ~/.aspect-gc.log 2>&1

Run it with the volumes your workspaces live on mounted: a workspace gc cannot find counts as gone.

Worktrees and agents

Each worktree is a new workspace path, so each gets its own output base, server and external/ tree. Deleting the worktree orphans them; gc removes them an hour after their last use. aspect worktree avoids that by reusing a pool of slots at fixed paths, each keeping one warm output base for its next lease. gc does not treat a pool slot’s base as orphaned, though it still removes one idle past --base-max-idle-days; aspect worktree prune deletes slots that have gone stale, base and all.

Scripting

Both tasks take --output=json. For example, the workspaces whose bases gc would remove:

aspect gc --dry-run --output=json | jq -r '.removals[].workspace'

​1. See what is there

​2. Preview

​3. Reclaim

​4. Tune the rules

​5. Run it on a schedule

​Worktrees and agents

​Scripting