muse gc — garbage-collect unreachable objects

Muse stores every tracked file as a content-addressed blob under .muse/objects/. Over time — after branch deletions, abandoned experiments, or squash merges — blobs that are no longer reachable from any live commit accumulate and waste disk space. muse gc identifies and removes them.

How it works

1. Reachability walk: Starting from every live branch head and tag, Muse walks the commit graph:

   branch HEAD → CommitRecord → SnapshotRecord → manifest → object SHA-256
   

2. Unreachable detection: Any object not reachable from step 1 is garbage.
3. Deletion (if not --dry-run): Unreachable objects are deleted. Empty prefix directories are also cleaned up.

Usage

muse gc                  # remove unreachable objects (safe default)
muse gc --dry-run        # show what would be removed without touching anything
muse gc --verbose        # print each removed object ID

Options

Output

Removed 12 object(s) (48.3 KiB) in 0.031s  [247 reachable]

In --dry-run mode:

[dry-run] Would remove 12 object(s) (48.3 KiB) in 0.028s  [247 reachable]

Safety guarantees

• The reachability walk always completes before any deletion begins.
• --dry-run is always safe to run — even in production, even by agents.
• GC never touches commit or snapshot records — only content blobs.
• Running GC is idempotent: running it twice produces the same result.

When to run

Agent workflows

# Audit unreachable bloat before a deployment:
muse gc --dry-run

# Automated nightly cleanup:
muse gc 2>&1 | logger -t muse-gc

Exit codes