> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Reclaim disk and memory from Bazel

> Find what Bazel is holding on a machine with aspect output-bases and reclaim it with aspect gc, by hand or on a schedule.

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`](/docs/cli/tasks/output_bases) shows what is there. It changes nothing.
* [`aspect gc`](/docs/cli/tasks/gc) removes what nothing is using.

## 1. See what is there

```shell theme={null}
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

```shell theme={null}
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.

```text theme={null}
  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

```shell theme={null}
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:

```shell theme={null}
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:

```shell theme={null}
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`](/docs/cli/worktrees) 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:

```shell theme={null}
aspect gc --dry-run --output=json | jq -r '.removals[].workspace'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.