residue

Find the Git worktrees left behind.

Coding agents leave full checkouts and build output behind. residue finds linked Git worktrees, measures their disk use and explains which checks keep them from removal.

Install Read the docs View source

Chart. A repository leads to its linked worktrees, then checks, then a report. Read only ends at scan and explain, which read and stop. A separate arrow, you or watch, enters remove, then fresh checks. The left arrow from fresh checks ends at stays when a check blocks, is unknown, or the worktree changed. A different pair of arrows, only when every check passes, goes to git remove without --force or to the trash for restore. The block path does not continue to deletion.

Install, then inspect

Homebrew · macOS and Linux

brew install whiteheap/tap/residue

residue needs Git 2.36 or later on PATH. Debian, Ubuntu, Fedora, Arch, prebuilt binaries and building from source are in the other ways to install. Downloads are on the latest release.

Look first

residue scan ~/src/app

~/src/app is an example path: replace it with your repository's path. scan only reads.

residue explain PATH

Replace PATH with one linked worktree's path to see every check, and why it passed or failed.

How it works

  1. Find and measure.

    residue inspects the linked worktrees Git lists for each repository, and their disk use.

  2. Understand the decision.

    Each worktree is a candidate, kept, or unknown, with the reason. A check residue could not complete keeps the worktree, the same as a failed one. What makes a worktree a candidate

  3. Choose what happens next.

    residue remove asks first, checks the worktree again, and hands the deletion to git worktree remove without --force. With --trash, which --idle turns on, the worktree stays restorable until the trash is purged; otherwise Git deletes it. Read the plan and the limits first. What removal deletes, and what it keeps

residue watch can remove worktrees on its own when a branch lands or the disk runs low, and it deletes without the trash. It runs only when you start it or install it as a service; scan never turns it on. Reclaim storage automatically

Before you remove anything

residue can delete directories. Start with scan and explain, and read the removal limits before you use cleanup. Activity checks cannot see every process or a paused session, and a write can still happen after the final check. Reported reclaimable space is an estimate. residue runs as you; it is not a security boundary between users.