atl gc

Reclaim orphaned assets — the reversible inverse of install. Finds files under the installed asset dirs (.claude/agents|skills|rules|knowledge|backends|scripts|packs) that no install manifest owns, plus stale promote conflict archives, and removes them without ever destroying anything irreversibly.

atl install / update / promote write assets into ~/.claude and <proj>/.claude and record each one in an install manifest. Nothing prunes what falls out of that contract — a file dropped upstream on an update (left on disk by design), a learning-loop gain left behind after a team is removed, or a directory you made by hand. Over time these accrete. atl gc is the missing cleanup half.

doctor heals; gc prunes. atl doctor restores manifest-listed files that went absent; atl gc removes files that no manifest owns. They are deliberate opposites — and gc never deletes irreversibly.

Usage

atl gc                          # report only — a dry run that touches nothing (default)
atl gc --apply                  # soft-delete unowned orphans to ~/.atl/gc-trash (reversible)
atl gc --apply --include-gains  # also reclaim gains beside installed units (opt-in)
atl gc --undo                   # restore the most recent soft-delete batch
atl gc --purge                  # hard-delete expired trash batches — the only real delete

Two classes are retained by default, and a plain atl gc --apply never touches either:

• Gains — a file beside an installed unit that no manifest lists: a children/ page a /drain grew, or a hand edit. Reported and kept, so the automatic awareness pass can never delete accumulated learning.
• Anything committed to the project's git. Nothing reaches a commit by accident, so a tracked file is content someone decided to keep — whatever put it there.

That second class exists because of a case the first one cannot catch. When a team is removed, its manifest goes with it, so everything in its directory becomes wholly unowned — including the knowledge the learning loop accumulated inside it. Measured on ATL's own workspace before the check existed: atl gc listed two hand-written skills, 15 KB and 10 KB with their own commit histories, as reclaimable — under a message that named the very case it could not distinguish ("a removed team or a hand-made dir").

Pass --include-gains only when you deliberately want both classes reclaimed. Files you atl pin are treated as owned and never flagged at all.

What counts as an orphan

atl gc walks both layers (~/.claude global and <proj>/.claude project), cross-references every asset file against that layer's install manifests, and flags anything no manifest owns. Each is labeled with a guessed origin — a hint, never a certainty:

Origin	What it usually means
gain or edit beside an installed unit	A file under an installed agent/skill (e.g. a children/ learning) that isn't in the manifest — often a learning-loop gain, sometimes a hand edit. Retained by --apply unless you pass --include-gains.
unowned unit (a removed team or a hand-made dir)	A whole agents/x or skills/x dir no manifest owns — a team that was removed leaving files behind, or your own non-ATL Claude Code assets.
expired conflict archive	A promote conflict archive under ~/.atl/history/ older than 30 days (these are content-addressed and never pruned otherwise).
ended session's guard state	A per-session directory under ~/.atl/cache/guard/ older than 14 days. atl guard writes one empty marker per file it has nudged, so nothing here outlives its session — but nothing removed them either, and because every marker is empty the tree is invisible to any size-based check (measured: 69 dirs, 2,372 markers). The cost is inodes, not bytes.

Because "no manifest owns it" also matches your own non-ATL assets, gc is dry-run by default and never deletes irreversibly — you always see the list before anything moves.

The reversible safety model

Deletion is the one place ATL can't be silently automatic, so gc makes the operation reversible instead of making it manual:

1. atl gc (default) — reports orphans by scope, origin, and size. Touches nothing.
2. atl gc --apply — soft-delete: moves each unowned orphan into a timestamped batch under ~/.atl/gc-trash/ and writes an undo manifest. Gains beside installed units are retained (see above); nothing is destroyed.
3. atl gc --apply --include-gains — additionally soft-delete the retained gains, when you deliberately want them gone.
4. atl gc --undo — restores the most recent batch to its original paths.
5. atl gc --purge — the only real delete: hard-removes trash batches older than 30 days.

So there is no irreversible data loss at any step. The action stays manual (you run atl gc), but awareness is automatic: a session-start note surfaces what --apply would actually reclaim (atl: N reclaimable item(s) — run atl gc to review (dry run; reversible)) so you never have to remember to check.

It used to count the set gc refuses

Until 2026-08-28 that note counted the retained gains instead — so it fired in every project, every session, and running the command it named could not change it: gc looked, said it was keeping them, and the next session said the same thing. The only flag that would have cleared it, --include-gains, deletes them. It now counts the swept set, which --apply empties, so the note is a state you can leave.

The gains are still reported — by atl gc itself, where they are labelled as gains rather than as orphans.

Related

• atl doctor — the heal half: restores manifest-listed files that went missing (gc is the prune half)
• atl remove — removes a team's manifest-listed files; gc catches what remove leaves behind
• atl promote — writes the conflict archives that gc expires after 30 days