kicad-tools: Command for Claude Code

/repo:tidy — Tidy Up

Sweep the working tree for clutter and clean it up. Inventory everything, categorize by confidence, then by default delete the SAFE category (pure junk that holds no unique work) and report what was freed. Regenerable caches (compilation/tool/build output) are kept by default and only cleared when you pass --caches — deleting them is harmless but forces a costly rebuild, so it is opt-in. Items that could be real work (ASK) are always presented for a human call, never auto-deleted.

Usage

/repo:tidy                    # Inventory, delete SAFE junk (caches kept), report; ASK items presented
/repo:tidy --caches           # Also clear regenerable caches (__pycache__/, dist/, .mypy_cache/, …)
/repo:tidy --ask              # Walk every category interactively before deleting anything
/repo:tidy --sizes            # Also measure worktree root sizes (slow: du has no prune)
/repo:tidy packages/core      # Scope to one subtree

(--apply is accepted as a synonym for the default, for muscle memory. --caches composes with --ask: --ask still walks every category, --caches just moves the cache tier into the auto-delete set for the non-interactive default. --sizes only adds the per-worktree size column described in step 1 — it never changes what is deleted.)

Steps

1. Inventory

Gather candidates without deleting anything:

# Ignored files that exist on disk (usually build output/caches)
git clean -ndX

# Untracked files (may include work-in-progress — treat carefully)
git clean -nd

# Empty directories
find . \( -name .git -o -name node_modules -o -name target \
          -o -name dist -o -name .venv \) -prune \
     -o -type d -empty -print

# Large files in the working tree (>10 MB, tracked or not)
find . \( -name .git -o -name node_modules -o -name target \
          -o -name dist -o -name .venv \) -prune \
     -o -type f -size +10M -print

# Orphaned environment content — packages still on disk that the current
# lockfile no longer references. Detect the lockfile and its package manager;
# the prune itself is an ASK item (see Categorize), never run from here.
[ -f pnpm-lock.yaml ]     && echo "prunable: pnpm"   # pnpm prune
[ -f package-lock.json ]  && echo "prunable: npm"    # npm prune

# Git worktree roots — authoritative and tool-agnostic. RETAIN this output as a
# path set for step 2's denylist; do not just print it. `--porcelain` gives one
# `worktree <path>` line per entry, including worktrees that live outside this
# repo root (`../repo-wt-fix123`, `/private/tmp/…`, `/private/var/folders/…`),
# which `git clean` never sees.
git worktree list --porcelain

# The worktree paths alone, for step 3's WORKTREES block. Extract them with
# `sed`, not `awk '{print $2}'`: awk splits on whitespace and would truncate
# `/repos/my checkout/wt` to `/repos/my`. The `worktree ` prefix is fixed, so
# stripping it with sed and reading whole lines keeps paths with spaces intact
# (paths containing newlines need `git worktree list --porcelain -z`).
git worktree list --porcelain | sed -n 's/^worktree //p'

# Worktree SIZES ARE NOT COLLECTED BY DEFAULT — only when `--sizes` is passed.
# See below for why. When it is passed, bound each root so a slow one degrades
# the size column instead of stalling the step:
git worktree list --porcelain | sed -n 's/^worktree //p' \
  | while IFS= read -r wt; do
      timeout 20 du -sh "$wt" 2>/dev/null \
        || printf '%s\t%s\n' 'size unavailable' "$wt"
    done