Skip to content
Back to skills

Gc

BSecurity

Inspect and safely clean stale local dev state: unused Git worktrees, merged branches, orphaned Bazel output bases, unreferenced repo-contents-cache entries. Use for pruning worktrees/branches or reclaiming Bazel disk — drive the `workspace-gc` tool and apply PR judgment to REVIEW items.

  • 11 stars
  • 0 votes
  • 0 copies
  • 6 views
  • Added September 9, 2026
toolsrustgoshellbashgitapi

Works with

  • claude code
  • api

Security analysis

B85/100
  • highPerforms destructive filesystem operations

Pro scans all 14 files and shows the line behind each finding

Scanned November 9, 2026

npx -y skills add agentydragon/ducktape --skill gc --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Gc?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Gc
[![Security: B — Skills Directory](https://www.skillsdirectory.com/api/skills/agentydragon-ducktape/badge)](https://www.skillsdirectory.com/skills/agentydragon-ducktape)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: workspace-gc
description: >-
  Inspect and safely clean stale local dev state: unused Git worktrees, merged
  branches, orphaned Bazel output bases, unreferenced repo-contents-cache
  entries. Use for pruning worktrees/branches or reclaiming Bazel disk — drive
  the `workspace-gc` tool and apply PR judgment to REVIEW items.
---

# Clean Workspaces

`workspace-gc` runs **one joint scan** over four coupled domains and classifies them
together (the domains depend on each other: a branch checked out in a live worktree can't be
deleted; an output base orphans when its workspace worktree is removed; a repo-cache entry is
unreferenced once the bases linking to it are gone):

- **worktrees** — local worktrees whose work is already merged;
- **branches** — local branches whose work is already in the default branch;
- **bazel-bases** — orphaned Bazel output bases (the default MD5-named ones and Claude Code's
  per-session ones) and bases linked to workspaces under `/tmp`;
- **repo-cache** — entries of Bazel's repo contents cache that no output base links to.

`workspace-gc` with no subcommand runs `all` (every domain). `workspace-gc worktrees`,
`workspace-gc bazel-bases` and `workspace-gc repo-cache` are **views** of that same computed
result, scoped to one domain.
All use the PRUNE/KEEP/REVIEW model, are dry by default, and revalidate every candidate
immediately before removing it, skipping (and exiting nonzero for) one that changed.
Gitignored files are not uncommitted changes: removing a worktree or foreign clone deletes
them (a gitignored `.env` or local data is lost), so inspect KEEP/REVIEW reasons for
anything you would miss.

Scans emit INFO progress to stderr as they inspect each worktree, branch, output base, PR
batch, or requested size, so a large or slow item is identifiable before the final report.

Git or filesystem failures inspecting a worktree, branch, or foreign clone produce `REVIEW`
with the error, leaving that item intact while other items continue. This also applies during
deletion revalidation. An existing directory with unreadable Git metadata is never treated as
a missing worktree. Failures that block the entire command exit nonzero with a diagnostic.
An item skipped at deletion (it no longer qualifies, or its Bazel lock or the cache is busy) is
reported as `SKIPPED` and does not change the exit status; a failed removal does.

**The tool automates what's easy to automate; you apply intelligence where the automation
needs supplementation.** It makes the clear-cut calls — an ancestor merge, a merged PR, a
missing workspace. You supplement: inspect the dirty KEEP trees the tool can't reason about
(build noise vs. real work), judge the REVIEW items, and never recreate its deletion logic
with an ad hoc script.

## Establish Intent And Scope

- If the user asks what _could_ be cleaned, inventory and report without deleting.
- If the user asks to clean up, remove clear candidates, report every ambiguous item, and
  summarize retained state. Do not turn that into permission to delete remote branches,
  unique work, shared caches, or unrelated build state.
- Keep the active worktree, the main checkout, and anything used by a running process.
- Never discard uncommitted changes on your own. Reverting (`git checkout`/`restore`,
  `git clean`, `worktree remove --force`) is destructive and requires explicit user
  approval each time — surface the finding and propose it, but let the user decide.
- Prefer the `workspace-gc` **binary already on PATH** — it is released via Nix and
  installed as part of `ducktape`, so it is present on your machines. Run it directly
  (`workspace-gc …`). Check with `command -v workspace-gc` first; only if it is absent
  (e.g. a bare Ducktape source checkout without the package installed) do you fall back
  to building+running it under Bazel: load the devshell and prefix the same args with
  `bb run //devinfra/gc:workspace_gc_bin --` — so `workspace-gc worktrees` becomes
  `bb run //devinfra/gc:workspace_gc_bin -- worktrees`.

## Inventory First

Run these read-only views before deleting anything:

```bash
workspace-gc                        # the default: worktrees + branches + bases together
workspace-gc --sizes                # add du-measured base sizes (slow on a large cache)
workspace-gc worktrees              # the worktree slice only
workspace-gc bazel-bases            # the output-base slice only
workspace-gc repo-cache             # the repo-contents-cache slice only
git worktree prune --dry-run --verbose   # stale admin records
```

Repo-cache reports summarize PRUNE and KEEP entries and list REVIEW entries; use `--verbose`
to list PRUNE entries and individual deletion results, or `--all` to list all cache entries.
Add `--all` to show KEEP rows in other domains too. Omit `--sizes` for a quick first pass on a large cache.
Pass `--no-prs` to skip the GitHub PR cross-check (offline, or to avoid one API call per
branch on a repo with many branches). The base scanner covers one output-user-root at a time
(default `$XDG_CACHE_HOME/bazel/_bazel_$USER`) plus, always, every Claude Code per-session base
(`~/.claude/session-env/*/bazel-output-base`, where each session's `bazelrc` points Bazel);
re-run with `--output-user-root PATH` for known custom cache locations rather than assuming the
default is the only root.

## Worktrees

`workspace-gc worktrees` classifies each worktree; interpret it literally:

- `PRUNE`: clean, idle (not main/active, no process cwd'd inside), and its work is already
  in the main branch — an ancestor, a squash/rebase-merge (merging into main is a no-op),
  an empty branch, or a **merged GitHub PR** for its branch. Remove with
  `workspace-gc worktrees --prune`: it re-classifies each worktree right before removing it, runs `git worktree remove` **without
  `--force`** (so a tree that turned dirty is skipped), and **never deletes branches** —
  the work stays reachable through them.
- `KEEP`: main checkout, the invoking worktree, uncommitted (tracked or untracked)
  changes, an open PR, or a live process. Not safe to auto-prune — but inspect it anyway
  (see below); most KEEP rows are dirty trees and the label alone doesn't say whether the
  dirt is real work.
- `REVIEW`: clean but has commits not in main and no merged PR, a detached HEAD with
  unique commits, or an undeterminable default branch. Judge these yourself — inspect the
  commits/PR and decide; removal must not make any commit unreachable.

The PR cross-check uses `GITHUB_TOKEN` or `gh auth token`; pass `--no-prs` to classify on
git signals only (offline). After pruning, re-run `git worktree prune --dry-run --verbose`
and run `git worktree prune --verbose` only if every listed record is confirmed stale.

### Inspect KEEP worktrees, don't just trust the label

`KEEP` means "not auto-prunable", not "leave unexamined". The tool cannot tell real
uncommitted work from build-tool noise, so look inside each dirty KEEP row and report its
real disposition. The report's `LAST ACTIVITY` column and the PR annotation on a dirty row
(`uncommitted changes (PR #N merged)`) are the first triage signals:

- **What is dirty?** `git -C PATH status --porcelain`, then `git -C PATH diff --stat`. If
  the only changes are regenerated or reformatted `BUILD.bazel` / other build-tool output
  (e.g. a buildifier reflow of a `third_party` file), that is noise, not work. Report it and
  **propose** reverting just those files (`git -C PATH checkout -- FILE`), which makes the
  tree flip to a clean PRUNE — but never run the revert without explicit user approval:
  `git checkout` discards uncommitted state and is not the agent's to decide.
- **How stale?** `git -C PATH rev-list --left-right --count origin/HEAD...HEAD`. A tree
  thousands of commits behind is almost certainly an abandoned spike; its uncommitted churn
  is stale mass-reformat noise, not recoverable work.
- **Is the work already safe elsewhere?** Commits pushed to a remote branch, or a merged PR
  (the report annotates the dirty row's PR state), survive worktree removal — so the tree
  can go once you confirm nothing uncommitted still matters.

Classify each dirty KEEP as build-noise, abandoned-spike, or live-WIP; only live-WIP is a
genuine keep.

## Branches

The joint scan (`workspace-gc`, shown in the `# Branches` section) classifies each local
branch; interpret it literally:

- `PRUNE`: its work is provably in the default branch and it is not held by a kept worktree —
  established by git (an ancestor, an empty branch, a squash/rebase-merge no-op, or every
  commit having a patch-equivalent already on the default branch) **or** by
  a merged PR whose merged head the branch has not advanced beyond. A branch checked out in a
  _prunable_ worktree is eligible too; `all --prune` removes that worktree first, then the
  branch. Deletion uses `git branch -D` (git's safe `-d` rejects squash-merges) **after
  re-proving** the branch is still prunable — safe because the content is in the default
  branch, but it removes the ref (recoverable only via reflog).
- `KEEP`: the default branch, a branch with an open PR, or a branch checked out in a retained
  worktree (git won't delete a checked-out branch anyway).
- `REVIEW`: commits not in the default branch and no merged PR, or a merged PR the branch has
  advanced beyond (unmerged local commits past the merge point). Judge these yourself —
  removal must not make any commit unreachable.

Branch deletion requires an explicit `--prune` and is never implied by the dry scan. The PR
cross-check uses `GITHUB_TOKEN` or `gh auth token`; `--no-prs` classifies on git signals
alone (so squash-merges the API would have confirmed fall to REVIEW).

## Bazel Output Bases

`workspace-gc bazel-bases` classifies each base; interpret it literally:

- `PRUNE`: a default MD5-named base, or a per-session base under `~/.claude/session-env/`,
  whose recorded workspace is absent or under `/tmp`, with no live server or nested mount. A
  server is live only when some process's argv names that very base as `--output_base` — a
  bare recorded PID proves nothing, since a sandboxed server records its namespace-local PID
  and a host PID is recycled once the server exits. Remove with `workspace-gc bazel-bases --delete`;
  it revalidates and locks every candidate before deletion. Deleting a `/tmp` output base
  leaves its workspace intact.
- `KEEP`: leave it alone. A base whose workspace is a **prunable worktree** outside `/tmp`
  stays KEEP in the `bazel-bases` view (its workspace still exists) but is annotated
  "workspace is a prunable worktree"; run `all --prune` to remove the worktree and then its
  newly orphaned base in one pass.
- `REVIEW`: inspect the stated metadata, ownership, symlink, mount, live-use, or
  failed-quarantine issue. Never convert `REVIEW` into `rm -rf` without proving what the
  directory is and why removal is safe.

Re-run the dry scan after deletion. A nonzero delete result (a failed removal) or a `.bazel-output-base-gc-*`
quarantine means cleanup is incomplete and needs inspection.

## Repo Contents Cache

Bazel stores every fetched repository once, under `<output user root>/cache/repos/v1/contents/
<hash>/<uuid>/` with a sibling `<uuid>.recorded_inputs`, and an output base uses it through the
symlink `external/<repo>`. Bazel's own GC (`--repo_contents_cache_gc_max_age`) is age-based,
runs only on an idle server, and never asks whether anything still links to an entry.
`workspace-gc repo-cache` does; interpret it literally:

- `PRUNE`: no output base the scan knows — the root's and the per-session ones — links to the
  entry. Remove with `workspace-gc repo-cache --delete`: it takes Bazel's `gc_lock`
  exclusively (every Bazel command holds it shared while it runs, so nothing can be fetching
  or linking meanwhile; a busy lock skips the round), re-lists the bases and their links,
  then removes the entry the way Bazel's GC does (recorded inputs first, directory via
  `_trash/`).
- `KEEP`: some base that itself stays (KEEP or REVIEW) links to it. An entry whose only
  referrers are **prunable bases** is KEEP in this view, annotated "only prunable bases
  reference it"; run `all --prune` to remove those bases and then the entry in one pass.
- `REVIEW`: a malformed name, a directory without its `.recorded_inputs` (or the reverse), a
  nested mount, or an unreadable entry. Never `rm -rf` one without proving what it is.

`LAST USED` is the recorded-inputs mtime, which Bazel touches on every cache hit. `--sizes`
runs `du` per entry and is slow on thousands of entries. The scan derives the cache location
from `--output-user-root` as Bazel's default does; a base under _another_ output user root
that points `--repo_contents_cache` at this cache is invisible, and an entry only it links to
is deleted — that base re-fetches the repo, the same exposure Bazel's own GC already creates.

## Leave Judgment Where It Belongs

Handle these manually per situation instead of expanding the tool's deletion surface:

- `REVIEW` worktrees (unmerged commits, detached heads, missing upstreams) and open PRs;
- stale directories that are not registered Git worktrees;
- `REVIEW` output bases and failed GC quarantines;
- nondefault output-base layouts and additional output-user-roots; and
- Bazel's shared repository (download), disk, and install caches.

`workspace-gc` deletes only **local** branches it proves are merged; deleting remote branches
is never implied — do that only when the user separately requests it and its safety is
established.

Finish with a concise ledger: worktrees removed and retained, branches deleted and retained,
output bases and repo-cache entries deleted, space reclaimed, roots scanned, and every item
still requiring review.

Files in this skill

  • BUILD.bazel3.3 KB
  • SKILL.md9.6 KB
  • branch_gc.py6.3 KB
  • git_repo.py5 KB
  • output_base_gc.py18.9 KB
  • pull_request.py843 B
  • test_bazel_output_base_gc.py11.7 KB
  • test_branch_gc.py7.4 KB
  • test_workspace_gc.py4 KB
  • test_workspace_scan.py7.2 KB
  • test_worktree_gc.py7.7 KB
  • workspace_gc.py18.9 KB
  • workspace_scan.py8.5 KB
  • worktree_gc.py6.6 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in tools →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.