agentleFS
tyler-berggrentyler-berggren/tb-claude-kit/.claude/skills/prune/SKILL.md

prune

Skill2 starsChanged 5 days agoMITView on GitHub

Review a repo's git worktrees and recommend which to remove — merged or abandoned branches, stale ones, and folders already gone — then remove only the ones the user picks. `/prune report` changes nothing. Optional path argument for a repo other than this one.

14 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use deliver, wizard and 3 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • GoogleSkill

    deliver

    Posts a condensed version of the briefing to a Google Chat or Slack incoming webhook, so the daily run delivers itself — skips silently when no webhook is configured.

    Also in 3 projects that use this

  • AWSSkill

    wizard

    Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.

    Also in 3 projects that use this

  • AWSSkill

    wait-what

    Stop. That last message did not land: re-pitch it.

    Also in 3 projects that use this

  • GoogleSkill

    prototype

    Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

    Also in 4 projects that use this

  • AWSSkill

    ship

    Finalize dev work on an issue branch — update docs, push, and open a PR.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 13 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run from the repo (or cd to the path argument first).

    line 46
  2. Distinctive:

    Never delete a remote branch.

    line 156
  3. Very specific:

    If .claude/kit.json has a rules."prune" entry, read it and apply it as an additional instruction for this skill.

    line 181

“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Prune Worktrees

A worktree is a second (or tenth) checkout of the same repo in its own folder, each on its own branch. Several branches can be open at once without stashing or switching, which is why agents and /swarm use them heavily. They are cheap to make and easy to forget. Each keeps its own node_modules and build output (often 1–3 GB), and after a few weeks most of them hold branches that were merged long ago.

This skill finds the ones you can let go, explains why for each, and removes only what you pick.

ArgumentWhat happens
(none)Review this repo's worktrees, recommend, ask, then remove what you choose.
reportReview and recommend only. Changes nothing.
<path>Same, for the repo at that path (e.g. a team repo this project wraps).

Configuration

Optional, in .claude/kit.json:

{
  "prune": {
    "staleDays": 14,
    "keep": ["release-*", "demo"]
  }
}
  • staleDays: no commit and no file change for this many days counts as stale. Default 14.
  • keep: branch-name globs never recommended for removal.

The shell is zsh, which aborts on unmatched globs and doesn't word-split variables. Every block below runs under bash.

Procedure

1. Gather the facts

Run from the repo (or cd to the path argument first). This only reads, plus one git fetch --prune, which updates what the remote knows and deletes no local work.

bash <<'SH'
set -u
REPO=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || { echo "not a git repo"; exit 1; }
MAIN=$(git worktree list --porcelain | awk 'NR==1{print $2}')
cd "$MAIN"
git fetch --prune --quiet 2>/dev/null || echo "note: fetch failed (offline?); merge status may be stale"
BASE=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || echo origin/main)
STALE=$(jq -r '.prune.staleDays // 14' .claude/kit.json 2>/dev/null); [ -z "$STALE" ] && STALE=14
GH=0; command -v gh >/dev/null && gh auth status >/dev/null 2>&1 && GH=1
# Every process's working directory, once, to spot worktrees something is running in.
CWDS=$(lsof -a -d cwd -Fn 2>/dev/null | sed -n 's/^n//p')
echo "main=$MAIN base=$BASE staleDays=$STALE gh=$GH"
printf 'path\tbranch\tdirty\tunpushed\tmerged\tpr\tlast_commit_days\tlast_touch_days\tsize\tbusy\tflags\n'
git worktree list --porcelain | awk '/^worktree /{p=$2} /^branch /{b=$2} /^detached/{b="(detached)"} /^locked/{l="locked"} /^prunable/{r="prunable"} /^$/{print p"\t"b"\t"l"\t"r; p=b=l=r=""} END{if(p)print p"\t"b"\t"l"\t"r}' |
while IFS=$'\t' read -r path ref locked prunable; do
  [ "$path" = "$MAIN" ] && continue
  br=${ref#refs/heads/}
  if [ -n "$prunable" ] || [ ! -d "$path" ]; then
    printf '%s\t%s\t-\t-\t-\t-\t-\t-\t-\t-\tfolder-gone\n' "$path" "$br"; continue
  fi
  dirty=$(git -C "$path" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
  if [ "$br" = "(detached)" ]; then unpushed=$(git -C "$path" rev-list --count HEAD --not --remotes 2>/dev/null)
  else unpushed=$(git -C "$path" rev-list --count "$br" --not --remotes 2>/dev/null); fi
  merged=no
  if [ "$br" != "(detached)" ]; then
    git merge-base --is-ancestor "$br" "$BASE" 2>/dev/null && merged=yes
    # Squash merges leave no ancestry; git cherry marks commits already upstream with "-".
    [ $merged = no ] && [ -z "$(git cherry "$BASE" "$br" 2>/dev/null | grep '^+')" ] && merged=patches-upstream
    git for-each-ref --format='%(upstream:track)' "refs/heads/$br" | grep -q gone && [ $merged = no ] && merged=upstream-gone
  fi
  pr=-
  [ $GH = 1 ] && [ "$br" != "(detached)" ] && pr=$(gh pr list --head "$br" --state all --limit 1 --json number,state --jq 'if length > 0 then "#\(.[0].number) \(.[0].state)" else "none" end' 2>/dev/null)
  [ -z "$pr" ] && pr=none
  lc=$(( ( $(date +%s) - $(git -C "$path" log -1 --format=%ct 2>/dev/null || echo 0) ) / 86400 ))
  # Newest file edit outside dependency and build folders.
  newest=$(find "$path" \( -name node_modules -o -name .git -o -name .next -o -name .turbo -o -name target -o -name dist \) -prune -o -type f -print0 2>/dev/null | xargs -0 stat -f %m 2>/dev/null | sort -n | tail -1)
  lt=$(( ( $(date +%s) - ${newest:-0} ) / 86400 ))
  size=$(du -sh "$path" 2>/dev/null | cut -f1)
  busy=no; echo "$CWDS" | grep -q "^$path\(/\|$\)" && busy=yes
  printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$path" "$br" "$dirty" "${unpushed:-?}" "$merged" "$pr" "$lc" "$lt" "$size" "$busy" "${locked:--}"
done
SH

Also check for a running swarm, whose worktrees must never be touched:

sqlite3 cowork/brain/BRAIN.db "select plan_id, status from swarm_runs where status in ('running','ready')" 2>/dev/null

2. Sort each worktree into one of four groups

Locks. Claude Code locks every agent worktree to the session that made it, and the lock outlives the agent: a long session can hold dozens of finished agents' worktrees. Read the lock with ~/.claude-kit/scripts/worktree-sweep --json <repo>. Each worktree's why says either "lock from session pid N, which has ended" (a dead lock, ignored here) or "locked by live session pid N". It returns verdict: ask for a worktree that is landed, clean and idle but still locked by a live session: a finished agent nobody released. Put those in Ask, not Keep. Unlock before removing (git worktree unlock <path>).

Apply the first rule that fits, top to bottom:

GroupRuleWhy
Keepbusy=yes, a live lock (below), the current session's own folder, a branch of a running swarm, or a branch matching prune.keepSomething is using it, or you said so.
Keepdirty > 0 or unpushed > 0It holds work that exists nowhere else. Say which files or commits, so the user can decide to push or discard them first.
KeepPR is OPEN, or last touched within staleDaysStill in play.
Removefolder-goneThe folder was deleted by hand; git still lists it. Costs nothing to clean.
Removemerged is yes / patches-upstream, or PR is MERGEDThe work is in the main branch. The branch and folder are leftovers.
AskPR is CLOSED (not merged), or merged=upstream-gone with no PRAbandoned or merged in a way git cannot prove. Everything is pushed, so nothing is lost locally, but the user decides.
AskEverything else older than staleDaysPushed, not merged, not recently touched: probably forgotten, maybe paused.

3. Show the recommendation, then ask

Show one numbered table per group, largest first, in plain words. Include the branch, what happened to it ("merged 12 days ago as PR #812", "PR closed without merging", "no activity for 23 days"), its size, and for Keep the reason. End with the total size of Remove.

Then ask which to remove, with an AskUserQuestion:

  • "Remove the N recommended (X GB)" (recommended)
  • "Remove the recommended ones and the ones marked Ask"
  • "Let me pick" (then take a list of numbers)
  • "Nothing for now"

In report mode, show the tables and stop.

4. Remove what was picked

For each chosen worktree, in the main checkout:

git worktree remove "<path>"                     # never --force

git worktree remove refuses a folder with uncommitted or untracked changes. That refusal is the safety net: report it, and never retry with --force. node_modules and other ignored build output do not block it and go with the folder.

Then deal with the branch:

  • Merged by ancestry: git branch -d <branch> (git confirms it is merged).
  • Merged as a squash PR (MERGED on GitHub, or patches-upstream): git branch -D <branch>. Git cannot see a squash merge, so -d would refuse. GitHub's MERGED state is the proof.
  • Ask group: keep the branch unless the user said to delete it too. Removing the folder alone is fully reversible: git worktree add <path> <branch> brings it back.
  • Never delete a remote branch.

Finish with git worktree prune, which clears records of folders that are already gone.

5. Report

List what was removed and the space freed. Recount with git worktree list rather than trusting the plan. Name anything that refused to go and why, plus the one command that brings each removed worktree back (git worktree add <path> <branch>).

Rules

  • Never remove without the user's pick, not even the obvious ones. report changes nothing.
  • Never --force, never git clean, never reset. If git refuses, report it.
  • Never touch the main checkout, the session's own worktree, a worktree locked by a live session (unless the user picks it from Ask), a running swarm's worktrees, or one with a process running in it.
  • Never delete a remote branch. Local cleanup only.
  • Uncommitted or unpushed work is always Keep. Tell the user what it is. If they then want it gone, they push it or discard it themselves, and /prune runs again.

Project overrides

If .claude/kit.json has a rules."prune" entry, read it and apply it as an additional instruction for this skill. Absent file or key means no overrides — that is the normal case.

jq -r '.rules."prune" // empty' .claude/kit.json 2>/dev/null

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.