davepoon/buildwithclaude / plugins/all-skills/skills/cleanup
cleanup
VerifiedReclaim disk space and prune branches left behind by AI coding agents - merged or abandoned git worktrees, merged branches, stale build artifacts (node_modules, .venv, target), old archives and backups, package caches, and old agent session logs. Use when the user runs /cleanup, says the disk is full, or asks to clean up worktrees, branches, or storage.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 4.4 KB |
| scripts/agent_cleanup.pyexecutable | script | 52.0 KB |
scripts/agent_cleanup.py
View on GitHub#!/usr/bin/env python3
"""agent-cleanup: reclaim the disk space that AI coding agents leave behind.
scan Read-only. Finds git worktrees, branches, build artifacts, archives
and backups, package caches and agent session logs. Classifies each
one and saves a numbered plan.
apply Re-checks the chosen plan items and acts only on those whose state
has not changed since the scan. Never force-removes a worktree unless
--force is given, and never touches origin unless --remote is given.
Classes:
REMOVE safe to reclaim: merged into the base branch, regenerable, or already gone
NEEDS-DECISION holds something unique: uncommitted or ignored files, unmerged commits,
build output, archives, logs
KEEP-ACTIVE open PR, recent work, or a new branch with no commits yet
SKIP main checkout, long-lived branch, locked, rebasing, in use by a process,
or on an unmounted drive
Python 3.9+ standard library only. Needs git; uses gh (GitHub CLI) when present
to see PR state, so squash-merged branches are recognised.
"""
from __future__ import annotations
import argparse
import concurrent.futures as cf
import datetime as dt
import fnmatch
import hashlib
import json
import os
import re
import shutil
import stat
import subprocess
import sys
import time
from pathlib import Path
VERSION = "1.0.0"
HOME = Path.home()
STATE_DIR = Path(os.environ.get("XDG_STATE_HOME") or HOME / ".local" / "state") / "agent-cleanup"
PLAN_FILE = STATE_DIR / "plan.json"
LOG_FILE = STATE_DIR / "history.jsonl"
PLAN_MAX_AGE_HOURS = 24
NOW = time.time()
os.environ["GIT_OPTIONAL_LOCKS"] = "0" # keep `git status` from rewriting the index during a scan
DAY = 86400
CLASSES = ("REMOVE", "NEEDS-DECISION", "KEEP-ACTIVE", "SKIP")
CATEGORIES = ("git", "artifacts", "archives", "caches", "agents", "trash")
LONG_LIVED = re.compile(r"^(main|master|trunk|develop|development|dev|staging|stage|production|prod|"
r"gh-pages|releases?(/.*)?)$")
# Where agents keep isolated checkouts outside the repo. Worktrees inside a repo
# (Claude Code's .claude/worktrees, .worktrees) come from `git worktree list`.
# Extra roots: --agent-root or AGENT_CLEANUP_WORKTREE_ROOTS (os.pathsep-separated).
AGENT_WORKTREE_ROOTS = [
"$CODEX_HOME/worktrees", # Codex app
"~/.cursor/worktrees", # Cursor parallel agents
"~/conductor/workspaces", # Conductor
"/var/tmp/vibe-kanban/worktrees", # Vibe Kanban (Linux default)
]
IN_REPO_WORKTREE_DIRS = (".claude/worktrees", ".worktrees")
# Agent logs, pruned by age. Each entry: agent, directory, what it holds, the
# agent's own retention setting, and what may be deleted: "files:<glob>" deletes
# matching files older than --keep-days (glob on the path relative to the
# directory; "!" entries are excluded), "dirs" deletes whole subdirectories whose
# newest file is older than --keep-days.
AGENT_DATA = [
("Claude Code", "~/.claude/projects", "session transcripts",
"cleanupPeriodDays in ~/.claude/settings.json (default 30)", ["*.jsonl", "!*/memory/*"]),
("Claude Code", "~/.claude/file-history", "file checkpoints", "cleanupPeriodDays", ["*"]),
("Claude Code", "~/.claude/debug", "debug logs", "cleanupPeriodDays", ["*"]),
("Claude Code", "~/.claude/shell-snapshots", "shell snapshots", "cleanupPeriodDays", ["*"]),
("Claude Code", "~/.claude/paste-cache", "pasted content", "cleanupPeriodDays", ["*"]),
("Codex", "$CODEX_HOME/sessions", "session rollouts", "none built in", ["*.jsonl"]),
("Codex", "$CODEX_HOME/archived_sessions", "archived sessions", "none built in", ["*.jsonl"]),
("Codex", "$CODEX_HOME/log", "logs", "none built in", ["*"]),
("Gemini CLI", "~/.gemini/tmp", "chat sessions", "general.sessionRetention (default 30d)",
["*/chats/*"]),
("OpenCode", "~/.local/share/opencode/snapshot", "undo snapshots per project",
'none built in; "snapshot": false disables them', "dirs"),
("OpenCode", "~/.local/share/opencode/log", "logs", "none built in", ["*"]),
]
# Directories an install or build recreates exactly: REMOVE in a stale project.
REGENERABLE = {
"node_modules", ".next", ".nuxt", ".svelte-kit", ".turbo", ".parcel-cache", ".angular",
".expo", ".tox", ".nox", ".pytest_cache", ".mypy_cache", ".ruff_cache", "target", ".gradle",
".terraform", "test-results", "playwright-report", ".playwright-mcp", ".dart_tool", "DerivedData",
}
# Output that may hold a release, an export or hand-installed packages: NEEDS-DECISION.
BUILD_OUTPUT = {"build", "dist", "out", "coverage", ".output", ".venv", "venv"}
ARTIFACT_DIRS = REGENERABLE | BUILD_OUTPUT
# Outside git there is no ignore check, so only unambiguous names qualify.
UNAMBIGUOUS = {
"node_modules", ".next", ".nuxt", ".svelte-kit", ".turbo", ".parcel-cache", ".angular",
".tox", ".nox", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".gradle", ".dart_tool",
}
# Ignored files that a merged worktree may lose without anyone missing them.
DISPOSABLE_NAMES = ARTIFACT_DIRS | {"__pycache__", ".DS_Store", "Thumbs.db", ".eslintcache", ".cache",
"next-env.d.ts", ".astro", ".vite"}
DISPOSABLE_SUFFIXES = (".pyc", ".pyo", ".tsbuildinfo", ".log", ".egg-info")
ARCHIVE_RE = re.compile(
r"\.(zip|tar|tgz|tbz2?|txz|tar\.(gz|bz2|xz|zst)|7z|rar|dump|sql|sql\.gz|bak|orig|old)$", re.I)
BACKUP_DIR_RE = re.compile(r"(^|[-_.])(bak|backup|backups|old|orig)([-_.]|$)", re.I)
# Never walked into while looking for repos, archives and backups.
WALK_SKIP = ARTIFACT_DIRS | {".git", "Library", "Applications", "snap", ".Trash"}
REMOVABLE_MEDIA = ("/media/", "/run/media/", "/mnt/", "/Volumes/")
# (name, command that prints the cache dir, fallback dir, prune command, note)
CACHES = [
("npm", ["npm", "config", "get", "cache"], "~/.npm", ["npm", "cache", "clean", "--force"], ""),
("pnpm", ["pnpm", "store", "path"], None, ["pnpm", "store", "prune"],
"prunes only packages no project references"),
("yarn", ["yarn", "cache", "dir"], None, ["yarn", "cache", "clean"], ""),
("bun", None, "~/.bun/install/cache", ["bun", "pm", "cache", "rm"], ""),
("pip", ["pip3", "cache", "dir"], None, ["pip3", "cache", "purge"], ""),
("uv", ["uv", "cache", "dir"], None, ["uv", "cache", "prune"], "prunes only unused entries"),
("go build", ["go", "env", "GOCACHE"], None, ["go", "clean", "-cache"], ""),
("Homebrew", ["brew", "--cache"], None, ["brew", "cleanup", "--prune=all"],
"also uninstalls outdated formula versions"),
("Xcode DerivedData", None, "~/Library/Developer/Xcode/DerivedData", None, ""),
]
# ---------------------------------------------------------------- helpers
def expand(p: str) -> Path:
codex_home = os.environ.get("CODEX_HOME") or str(HOME / ".codex")
return Path(os.path.expanduser(p.replace("$CODEX_HOME", codex_home)))
def run(args, cwd=None, timeout=120):
try:
return subprocess.run(args, cwd=cwd, capture_output=True, text=True, timeout=timeout,
stdin=subprocess.DEVNULL)
except (OSError, subprocess.TimeoutExpired):
return None
def git(repo, *args, timeout=120):
"""stdout of a git command, or None when it fails."""
p = run(["git", "-C", str(repo), *args], timeout=timeout)
return p.stdout.strip() if p and p.returncode == 0 else None
def git_ok(repo, *args) -> bool:
p = run(["git", "-C", str(repo), *args])
return bool(p) and p.returncode == 0
def du(path) -> int:
"""Bytes on disk under path (0 when missing)."""
path = Path(path)
if not path.exists() and not path.is_symlink():
return 0
if path.is_symlink() or path.is_file():
return path.lstat().st_size
p = run(["du", "-sk", str(path)], timeout=900)
if p and p.stdout.split():
try:
return int(p.stdout.split()[0]) * 1024
except ValueError:
pass
total = 0
for root, _dirs, files in os.walk(path):
for f in files:
try:
total += os.lstat(os.path.join(root, f)).st_size
except OSError:
pass
return total
def human(n: int) -> str:
for unit in ("B", "KB", "MB", "GB", "TB"):
if abs(n) < 1024 or unit == "TB":
return f"{n:.0f} {unit}" if unit in ("B", "KB") else f"{n:.1f} {unit}"
n /= 1024
return str(n)
def parse_size(s: str) -> int:
m = re.fullmatch(r"(\d+(?:\.\d+)?)\s*([KMGT]?)B?", s.strip(), re.I)
if not m:
raise argparse.ArgumentTypeError(f"bad size: {s}")
return int(float(m.group(1)) * 1024 ** "_KMGT".index(m.group(2).upper() or "_"))
def short(p) -> str:
s = str(p)
h = str(HOME)
return "~" + s[len(h):] if s == h or s.startswith(h + os.sep) else s
def day(ts: float) -> str:
return dt.datetime.fromtimestamp(ts).strftime("%Y-%m-%d")
def tree_stamp(path: Path, skip=frozenset(), limit=200_000):
"""(newest mtime, entry count, complete) over a whole tree, not entering .git or `skip` names."""
try:
newest = path.lstat().st_mtime
except OSError:
return 0.0, 0, True
if path.is_symlink() or not path.is_dir():
return newest, 1, True
count = 0
for root, dirs, files in os.walk(path):
dirs[:] = [d for d in dirs if d != ".git" and d not in skip]
for n in dirs + files:
try:
newest = max(newest, os.lstat(os.path.join(root, n)).st_mtime)
except OSError:
pass
count += 1
if count > limit:
return newest, count, False
return newest, count, True
def process_cwds():
"""Working directories of every process we can see, or None if they can't be listed."""
cwds = set()
if Path("/proc").is_dir():
for d in os.listdir("/proc"):
if d.isdigit():
try:
cwds.add(os.readlink(f"/proc/{d}/cwd"))
except OSError:
pass
return sorted(cwds)
p = run(["lsof", "-d", "cwd", "-Fn"], timeout=180) # macOS and other BSDs
if not p or not p.stdout:
return None
return sorted(line[1:] for line in p.stdout.splitlines() if line.startswith("n/"))
def in_use(path: str, cwds) -> bool:
"""A process runs inside path. Unknown process list counts as in use."""
if cwds is None:
return True
real = os.path.realpath(path)
return any(c in (path, real) or c.startswith(path + os.sep) or c.startswith(real + os.sep)
for c in cwds)
def drive_unmounted(path: str) -> bool:
"""A missing path on removable media whose drive is not mounted.
Mounted means some existing ancestor below the media root is a mount point.
"""
prefix = next((m for m in REMOVABLE_MEDIA if path.startswith(m)), None)
if not prefix:
return False
p = Path(path).parent
while str(p) + "/" != prefix and len(p.parts) > 1:
if p.exists() and os.path.ismount(p):
return False
p = p.parent
return True
def safe_rmtree(path: Path):
"""Delete a file or tree, refusing anything that looks like a root or a home folder."""
path = Path(os.path.abspath(path))
if len(path.parts) < 3 or path in (HOME, HOME.parent, Path("/")) or path.parent == HOME:
raise RuntimeError(f"refusing to delete {path}")
if path.is_symlink() or path.is_file():
path.unlink()
return
def onerror(func, p, _exc): # read-only files and folders (node_modules, Go modules)
for target in (os.path.dirname(p), p):
try:
os.chmod(target, stat.S_IRWXU)
except OSError:
pass
func(p)
if sys.version_info >= (3, 12):
shutil.rmtree(path, onexc=onerror)
else:
shutil.rmtree(path, onerror=onerror)
def item(kind, cls, path, note, size=0, **extra):
d = {"kind": kind, "class": cls, "path": str(path) if path else "", "note": note, "size": size}
d.update(extra)
d["key"] = "|".join([kind, d["path"], d.get("repo", ""), d.get("branch", "")])
return d
# ---------------------------------------------------------------- git
def default_base(repo) -> str:
head = git(repo, "symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD")
if head:
return head.split("/", 1)[1]
for b in ("main", "master", "trunk", "develop"):
if git_ok(repo, "rev-parse", "-q", "--verify", f"refs/heads/{b}"):
return b
return git(repo, "branch", "--show-current") or "main"
def pr_states(repo, base) -> dict:
"""branch -> (state, number, headOid). A PR merged into another branch doesn't count as merged."""
if not shutil.which("gh") or os.environ.get("AGENT_CLEANUP_NO_GH"):
return {}
p = run(["gh", "pr", "list", "--state", "all", "--limit", "1000",
"--json", "headRefName,state,number,headRefOid,baseRefName"], cwd=repo, timeout=60)
if not p or p.returncode != 0:
return {}
prs = {}
for pr in reversed(json.loads(p.stdout or "[]")): # oldest first, so newer ones overwrite
state = pr["state"]
if state == "MERGED" and pr.get("baseRefName") != base:
state = "CLOSED" # merged into a stacked parent, not into base
cur = prs.get(pr["headRefName"])
if cur is None or state != "CLOSED":
prs[pr["headRefName"]] = (state, pr["number"], pr["headRefOid"])
return prs
def worktrees(repo):
"""Parsed `git worktree list --porcelain`."""
out = git(repo, "worktree", "list", "--porcelain") or ""
wts, cur = [], None
for line in out.splitlines() + [""]:
if line.startswith("worktree "):
cur = {"path": line[9:], "head": "", "branch": "", "locked": False, "bare": False}
elif cur is None:
continue
elif line.startswith("HEAD "):
cur["head"] = line[5:]
elif line.startswith("branch "):
cur["branch"] = re.sub(r"^refs/heads/", "", line[7:])
elif line.startswith("locked"):
cur["locked"] = True
elif line == "bare":
cur["bare"] = True
elif line == "":
wts.append(cur)
cur = None
return wts
def rebasing_branch(path):
"""Branch being rebased in this checkout, or None."""
gitdir = git(path, "rev-parse", "--absolute-git-dir")
for d in ("rebase-merge", "rebase-apply"):
f = Path(gitdir or "/nonexistent") / d / "head-name"
if f.is_file():
return re.sub(r"^refs/heads/", "", f.read_text().strip())
return None
def disposable(rel: str) -> bool:
parts = rel.rstrip("/").split("/")
return any(p in DISPOSABLE_NAMES for p in parts) or rel.rstrip("/").endswith(DISPOSABLE_SUFFIXES)
class RepoScan:
"""Classifies one repository's worktrees and local branches."""
def __init__(self, repo: Path, opts, cwds):
self.repo, self.opts, self.cwds = repo, opts, cwds
self.base = opts.base or default_base(repo)
self.base_ref = f"origin/{self.base}"
if not git_ok(repo, "rev-parse", "-q", "--verify", f"refs/remotes/{self.base_ref}"):
self.base_ref = self.base
self.base_tree = git(repo, "rev-parse", f"{self.base_ref}^{{tree}}")
self.prs = pr_states(repo, self.base) if self.base_tree else {}
def content_merged(self, head) -> bool:
"""True when merging head into base changes nothing (catches squash and rebase merges)."""
p = run(["git", "-C", str(self.repo), "merge-tree", "--write-tree", self.base_ref, head])
if p and p.returncode == 0:
return p.stdout.split("\n", 1)[0].strip() == self.base_tree
if p and p.returncode == 1: # conflicts
return False
return git_ok(self.repo, "merge-base", "--is-ancestor", head, self.base_ref) # git < 2.38
def creation(self, br):
"""(reflog entries, creation time) for a local branch; (0, None) without a reflog."""
log = git(self.repo, "reflog", "show", "--date=unix", "--format=%gd", f"refs/heads/{br}", "--")
stamps = re.findall(r"@\{(\d+)\}", log or "")
return (len(stamps), float(stamps[-1])) if stamps else (0, None)
def upstream_alive(self, br) -> bool:
up = git(self.repo, "rev-parse", "--abbrev-ref", "--symbolic-full-name", f"{br}@{{upstream}}")
return bool(up) and git_ok(self.repo, "rev-parse", "-q", "--verify", f"refs/remotes/{up}")
def no_own_commits(self, br, head, age):
"""Class for a branch whose head is already an ancestor of base."""
stale = self.opts.stale_days
entries, created = self.creation(br) if br else (0, None)
if entries == 1: # only the creation entry: nothing was ever committed to it
if NOW - created <= stale * DAY:
return "KEEP-ACTIVE", "new branch, no commits yet"
return "REMOVE", f"created {day(created)}, never committed to"
if entries == 0:
if age <= stale:
return "KEEP-ACTIVE", "no commits of its own; recent"
return "NEEDS-DECISION", "no commits of its own; no reflog to tell new from merged"
if br and self.upstream_alive(br):
return "KEEP-ACTIVE", "tracks a live remote branch; no commits beyond base"
return "REMOVE", f"merged into {self.base_ref}"
def classify(self, kind, br, path, head, dirty, kept, locked, main_wt):
"""kept: ignored files git would delete that don't look regenerable."""
state, num, oid = self.prs.get(br, ("", "", "")) if br else ("", "", "")
last = float(git(self.repo, "log", "-1", "--format=%ct", head) or 0)
touched = last
if path:
idx = git(path, "rev-parse", "--path-format=absolute", "--git-path", "index")
if idx and os.path.exists(idx):
touched = max(touched, os.stat(idx).st_mtime)
age = int((NOW - touched) // DAY)
unpushed = git(self.repo, "rev-list", "--count", head, "--not", "--remotes") or "?"
pr = f"PR #{num} {state.lower()}" if num else "no PR"
stale = self.opts.stale_days
if path == main_wt or br == self.base:
cls, note = "SKIP", "main checkout / base branch"
elif br and LONG_LIVED.match(br):
cls, note = "SKIP", "long-lived branch"
elif locked:
cls, note = "SKIP", "locked"
elif path and in_use(path, self.cwds):
cls, note = "SKIP", "in use (a process is running inside it)"
elif dirty is None:
cls, note = "NEEDS-DECISION", "git status failed; check it by hand"
elif dirty:
cls, note = "NEEDS-DECISION", f"{dirty} uncommitted path(s), {pr}"
elif kept:
shown = ", ".join(kept[:3]) + (", ..." if len(kept) > 3 else "")
cls, note = "NEEDS-DECISION", f"{len(kept)} ignored file(s) removal would delete: {shown}"
elif state == "OPEN":
cls, note = "KEEP-ACTIVE", f"PR #{num} open"
else:
merged = self.content_merged(head)
if state == "MERGED" and (oid == head or merged):
cls, note = "REMOVE", f"PR #{num} merged"
elif merged and git_ok(self.repo, "merge-base", "--is-ancestor", head, self.base_ref):
cls, note = self.no_own_commits(br, head, age)
elif merged:
cls, note = "REMOVE", f"content already on {self.base_ref}"
elif state == "MERGED":
cls, note = "NEEDS-DECISION", f"commits after PR #{num} merged, {unpushed} unpushed"
elif age <= stale:
cls, note = "KEEP-ACTIVE", f"touched {age}d ago, {pr}"
elif state == "CLOSED":
cls, note = "NEEDS-DECISION", f"PR #{num} closed unmerged, {unpushed} unpushed"
else:
cls, note = "NEEDS-DECISION", f"stale {age}d, no PR, {unpushed} unpushed commit(s)"
return item(kind, cls, path, note, repo=str(self.repo), branch=br or "", head=head,
fingerprint=f"{head}:{dirty}:{len(kept)}", last_commit=day(last) if last else "")
def scan(self):
if not self.base_tree:
return [item("repo", "SKIP", self.repo, f"no base branch '{self.base}' found",
repo=str(self.repo))]
out, taken = [], set() # taken: branches handled with their worktree
wts = worktrees(self.repo)
main_wt = wts[0]["path"] if wts else str(self.repo)
for wt in wts:
path, br = wt["path"], wt["branch"]
if wt["bare"]:
taken.add(br)
continue
if not os.path.isdir(path):
if drive_unmounted(path):
taken.add(br)
out.append(item("worktree", "SKIP", path, "drive not mounted",
repo=str(self.repo), branch=br))
else: # the branch is classified on its own below
out.append(item("worktree", "REMOVE", path, "directory is gone; unregister it",
repo=str(self.repo), registered_branch=br, head=wt["head"],
fingerprint=f"missing:{wt['head']}"))
continue
taken.add(br)
rebasing = rebasing_branch(path)
if rebasing:
taken.add(rebasing)
out.append(item("worktree", "SKIP", path, f"rebase of {rebasing} in progress",
repo=str(self.repo), branch=br))
continue
p = run(["git", "-C", path, "status", "--porcelain", "--ignored"])
dirty, kept = None, []
if p and p.returncode == 0:
lines = p.stdout.splitlines()
dirty = sum(1 for line in lines if not line.startswith("!! "))
kept = [line[3:] for line in lines if line.startswith("!! ") and not disposable(line[3:])]
out.append(self.classify("worktree", br, path, wt["head"], dirty, kept, wt["locked"], main_wt))
refs = git(self.repo, "for-each-ref", "--format=%(refname:short)%09%(objectname)",
"refs/heads") or ""
for line in refs.splitlines():
br, head = line.split("\t")
if br not in taken:
out.append(self.classify("branch", br, "", head, 0, [], False, main_wt))
if self.opts.remote:
out += self.remote_items(out)
return out
def remote_items(self, local):
"""origin branches whose local copy is REMOVE and whose remote tip is merged too."""
out = []
for it in local:
br = it.get("branch")
if it["class"] != "REMOVE" or not br:
continue
sha = git(self.repo, "rev-parse", "-q", "--verify", f"refs/remotes/origin/{br}")
if not sha:
continue
state, num, oid = self.prs.get(br, ("", "", ""))
if (state == "MERGED" and oid == sha) or self.content_merged(sha):
out.append(item("remote-branch", "REMOVE", "", f"origin/{br} is merged",
repo=str(self.repo), branch=br, fingerprint=sha))
return out
def main_repo_of(path: Path):
"""Main repository for a checkout (linked worktree or clone); None for submodules."""
if git(path, "rev-parse", "--show-superproject-working-tree"):
return None
common = git(path, "rev-parse", "--path-format=absolute", "--git-common-dir")
if not common:
return None
common = Path(common)
return common.parent if common.name == ".git" else common # else: bare repository
def gitdir_target(dotgit: Path):
"""For a linked worktree's .git file: the admin dir it points to."""
try:
text = dotgit.read_text(errors="replace").strip()
except OSError:
return None
if not text.startswith("gitdir:"):
return None
target = Path(text[7:].strip())
return target if target.is_absolute() else (dotgit.parent / target)
def is_orphan(d: Path) -> bool:
"""A linked worktree whose admin dir (and usually whole repo) no longer exists."""
dotgit = d / ".git"
if not dotgit.is_file():
return False
target = gitdir_target(dotgit)
if target is None:
return False
if target.exists():
return False
return not drive_unmounted(str(target))
# ---------------------------------------------------------------- discovery
def walk(root: Path, depth: int):
"""Yield (dirpath, dirnames, filenames) to `depth`, skipping WALK_SKIP and dot dirs."""
root_depth = len(root.parts)
for dirpath, dirnames, filenames in os.walk(root):
d = Path(dirpath)
keep = []
for n in dirnames:
if n in WALK_SKIP or (n.startswith(".") and n not in (".claude", ".worktrees")):
continue
if (d / n).is_symlink():
continue
keep.append(n)
dirnames[:] = keep if len(d.parts) - root_depth < depth else []
yield d, dirnames, filenames
def discover(roots, agent_roots, depth):
"""Repos, orphaned worktrees and backup/archive candidates under the given roots."""
repos, orphans, candidates = set(), [], []
def checkout(d: Path):
dotgit = d / ".git"
if dotgit.is_dir():
repos.add(d)
elif is_orphan(d):
orphans.append(d)
elif dotgit.is_file():
main = main_repo_of(d)
if main:
repos.add(main)
for root in agent_roots:
for d, dirnames, _ in walk(root, 3):
if (d / ".git").exists():
checkout(d)
dirnames[:] = []
for root in roots:
for d, dirnames, filenames in walk(root, depth):
if (d / ".git").exists():
checkout(d)
for n in list(dirnames):
if BACKUP_DIR_RE.search(n):
candidates.append(d / n)
dirnames.remove(n)
candidates += [d / f for f in filenames if ARCHIVE_RE.search(f)]
for repo in list(repos):
for sub in IN_REPO_WORKTREE_DIRS:
base = repo / sub
if base.is_dir():
orphans += [d for d in base.iterdir() if is_orphan(d)]
return sorted(repos), sorted(set(orphans)), candidates
def deep_fingerprint(p: Path):
newest, count, _ = tree_stamp(p)
return newest, f"{int(newest)}:{count}"
def orphan_items(orphans, cwds):
out = []
for d in orphans:
if in_use(str(d), cwds):
continue
_, fp = deep_fingerprint(d)
out.append(item("orphan-worktree", "NEEDS-DECISION", d,
"worktree whose repository is gone; any changes in it exist nowhere else",
fingerprint=fp))
return out
def candidate_items(candidates, opts, cwds):
out = []
for p in candidates:
if not (p.exists() or p.is_symlink()) or (p.is_dir() and in_use(str(p), cwds)):
continue
newest, fp = deep_fingerprint(p)
if NOW - newest < opts.stale_days * DAY:
continue
if main_repo_of(p.parent) and git(p.parent, "ls-files", "--", p.name):
continue # tracked in git: part of the project, not a leftover
kind = "backup" if p.is_dir() else "archive"
note = f"untouched since {day(newest)}"
if (p / ".git").exists():
note += "; contains a git checkout (check for unpushed work)"
out.append(item(kind, "NEEDS-DECISION", p, note, fingerprint=fp))
return out
def artifact_dirs(project: Path, is_git: bool):
"""Regenerable and build-output dirs inside a project."""
found = []
root_depth = len(project.parts)
for dirpath, dirnames, _ in os.walk(project):
d = Path(dirpath)
keep = []
for n in dirnames:
p = d / n
if n == ".git" or p.is_symlink():
continue
if d != project and (p / ".git").exists():
continue # nested checkout: scanned on its own
if n in ARTIFACT_DIRS:
if is_artifact(project, p, n, is_git):
found.append(p)
continue
keep.append(n)
dirnames[:] = keep if len(d.parts) - root_depth < 4 else []
return found
def is_artifact(project, p: Path, name, is_git) -> bool:
if name in ("venv", ".venv") and not (p / "pyvenv.cfg").exists():
return False
if name == "target" and not any((p.parent / m).exists() for m in ("Cargo.toml", "pom.xml")):
return False
if is_git:
rel = os.path.relpath(p, project)
return git_ok(project, "check-ignore", "-q", rel) and not git(project, "ls-files", "--", rel)
return name in UNAMBIGUOUS or name in ("venv", ".venv", "target")
def project_touched(project: Path, is_git: bool):
"""Newest activity in a project outside its artifact dirs, or None if too big to tell."""
newest, _, complete = tree_stamp(project, skip=ARTIFACT_DIRS)
if not complete:
return None
if is_git:
newest = max(newest, float(git(project, "log", "-1", "--format=%ct") or 0))
idx = git(project, "rev-parse", "--path-format=absolute", "--git-path", "index")
if idx and os.path.exists(idx):
newest = max(newest, os.stat(idx).st_mtime)
return newest
def artifact_items(project: Path, is_git: bool, opts, cwds):
touched = project_touched(project, is_git)
if touched is None or NOW - touched < opts.stale_days * DAY or in_use(str(project), cwds):
return []
out = []
dirs = artifact_dirs(project, is_git)
for kind, cls, names, why in (
("artifacts", "REMOVE", REGENERABLE, "the next install or build recreates them"),
("build-output", "NEEDS-DECISION", BUILD_OUTPUT, "may hold a release, export or hand-installed packages")):
mine = [p for p in dirs if p.name in names]
if mine:
listed = ", ".join(sorted({p.name for p in mine}))
out.append(item(kind, cls, project, f"{listed} in a project untouched since {day(touched)}; {why}",
paths=[str(p) for p in mine], is_git=is_git, fingerprint=str(int(touched))))
return out
# ---------------------------------------------------------------- storage
def cache_items():
out = []
for name, locate, fallback, cmd, note in CACHES:
path = None
if locate and shutil.which(locate[0]):
p = run(locate, cwd=str(HOME), timeout=30)
if p and p.returncode == 0 and p.stdout.strip():
path = Path(p.stdout.strip().splitlines()[-1])
if path is None and fallback:
path = expand(fallback)
if path is None or not path.exists():
continue
if name == "npm":
path = path / "_cacache"
if cmd and not shutil.which(cmd[0]):
continue
how = " ".join(cmd) if cmd else "delete contents"
out.append(item("cache", "REMOVE", path,
f"{name} cache; `{how}`" + (f" ({note})" if note else ""),
name=name, command=cmd or []))
if shutil.which("docker"):
p = run(["docker", "system", "df", "--format", "{{.Type}}\t{{.Reclaimable}}"], timeout=20)
if p and p.returncode == 0:
for line in p.stdout.splitlines():
kind, _, rec = line.partition("\t")
if kind == "Build Cache":
m = re.match(r"([\d.]+)\s*([kKMGT]?B)", rec)
size = parse_size(m.group(1) + m.group(2).upper()[0]) if m and m.group(2) != "B" else 0
out.append(item("cache", "REMOVE", "", "docker build cache; `docker builder prune -f`",
size=size, name="docker", command=["docker", "builder", "prune", "-f"]))
return out
def prunable(path: Path, rule, keep_days: int):
"""(path, size) of what an agent-data rule allows deleting: old matching files, or old subdirs."""
cutoff = NOW - keep_days * DAY
if rule == "dirs":
for d in sorted(path.iterdir()):
if d.is_dir() and not d.is_symlink():
newest, _, complete = tree_stamp(d)
if complete and newest < cutoff:
yield str(d), du(d)
return
include = [g for g in rule if not g.startswith("!")]
exclude = [g[1:] for g in rule if g.startswith("!")]
for root, _dirs, files in os.walk(path):
for f in files:
fp = os.path.join(root, f)
rel = os.path.relpath(fp, path)
if not any(fnmatch.fnmatch(rel, g) for g in include) or any(fnmatch.fnmatch(rel, g) for g in exclude):
continue
try:
st = os.lstat(fp)
except OSError:
continue
if st.st_mtime < cutoff:
yield fp, st.st_size
def agent_data_items(opts):
out = []
for agent, d, what, retention, rule in AGENT_DATA:
path = expand(d)
if not path.is_dir():
continue
old = sum(size for _, size in prunable(path, rule, opts.keep_days))
if old < opts.min_size:
continue
out.append(item("agent-data", "NEEDS-DECISION", path,
f"{agent} {what} older than {opts.keep_days}d; retention: {retention}",
size=old, agent=agent, rule=rule, keep_days=opts.keep_days))
return out
def trash_entries(t: Path):
"""Top-level items in the trash (Linux keeps them under files/ and info/)."""
entries = []
for sub in ((t / "files", t / "info") if (t / "files").is_dir() else (t,)):
if sub.is_dir():
entries += sorted(sub.iterdir())
return entries
def trash_fingerprint(t: Path) -> str:
h = hashlib.sha1()
for e in trash_entries(t):
try:
h.update(f"{e}:{int(e.lstat().st_mtime)}\n".encode())
except OSError:
pass
return h.hexdigest()
def trash_items(opts):
for t in (HOME / ".local/share/Trash", HOME / ".Trash"):
if t.is_dir():
size = du(t)
if size >= opts.min_size:
return [item("trash", "NEEDS-DECISION", t, "files already deleted to the trash",
size=size, fingerprint=trash_fingerprint(t))]
return []
# ---------------------------------------------------------------- scan
def scan(opts):
cwds = process_cwds()
if cwds is None:
print("warning: could not list running processes; every worktree is treated as in use",
file=sys.stderr)
agent_roots = [expand(p) for p in AGENT_WORKTREE_ROOTS + opts.agent_root
+ [p for p in os.environ.get("AGENT_CLEANUP_WORKTREE_ROOTS", "").split(os.pathsep) if p]]
agent_roots = [p for p in agent_roots if p.is_dir()]
roots = [Path(os.path.abspath(os.path.expanduser(r))) for r in opts.root]
repos, orphans, candidates = discover(roots, agent_roots, opts.depth)
for r in opts.repo:
main = main_repo_of(Path(r).expanduser())
if main:
repos.append(main)
repos = sorted(set(repos))
cats = set(opts.only or CATEGORIES)
items = []
if opts.fetch and "git" in cats:
with cf.ThreadPoolExecutor(8) as ex:
list(ex.map(lambda r: run(["git", "-C", str(r), "fetch", "--prune", "--quiet"], timeout=120),
repos))
if "git" in cats:
with cf.ThreadPoolExecutor(8) as ex:
for res in ex.map(lambda r: RepoScan(r, opts, cwds).scan(), repos):
items += res
items += orphan_items(orphans, cwds)
if "artifacts" in cats:
removable = {i["path"] for i in items if i["class"] == "REMOVE"}
projects = {}
for r in repos:
for wt in worktrees(r):
if not wt["bare"] and os.path.isdir(wt["path"]) and wt["path"] not in removable:
projects.setdefault(Path(wt["path"]), True)
for root in roots: # non-git projects directly under a root
for d in sorted(root.iterdir()) if root.is_dir() else []:
if d.is_dir() and not (d / ".git").exists() and not d.name.startswith("."):
projects.setdefault(d, False)
with cf.ThreadPoolExecutor(8) as ex:
for res in ex.map(lambda kv: artifact_items(kv[0], kv[1], opts, cwds), projects.items()):
items += res
if "archives" in cats:
items += candidate_items(candidates, opts, cwds)
if "caches" in cats:
items += cache_items()
if "agents" in cats:
items += agent_data_items(opts)
if "trash" in cats:
items += trash_items(opts)
def size_of(i): # only what could be reclaimed is measured
if i["size"] or not i["path"] or i["kind"] == "branch" or i["class"] in ("KEEP-ACTIVE", "SKIP"):
return i["size"]
if "paths" in i:
return sum(du(p) for p in i["paths"])
return du(i["path"])
with cf.ThreadPoolExecutor(8) as ex:
for i, size in zip(items, ex.map(size_of, items)):
i["size"] = size
# Storage-only items below the threshold are noise; git items always show.
items = [i for i in items if i["kind"] in ("worktree", "branch", "remote-branch", "orphan-worktree",
"repo") or i["size"] >= opts.min_size]
order = {c: n for n, c in enumerate(CLASSES)}
items.sort(key=lambda i: (order[i["class"]], -i["size"], i["kind"], i["path"], i.get("branch", "")))
for n, i in enumerate(items, 1):
i["id"] = n
return items
def render(items, show_all: bool):
header = {
"REMOVE": "REMOVE: safe to reclaim (merged, regenerable, or already gone)",
"NEEDS-DECISION": "NEEDS-DECISION: holds something unique; delete only on an explicit pick",
"KEEP-ACTIVE": "KEEP-ACTIVE: in use or recent; left alone",
"SKIP": "SKIP: never touched",
}
lines = []
for cls in CLASSES:
group = [i for i in items if i["class"] == cls]
if not group:
continue
total = sum(i["size"] for i in group)
lines.append(f"\n{header[cls]} [{len(group)} item(s), {human(total)}]")
if cls in ("KEEP-ACTIVE", "SKIP") and not show_all:
lines.append(" (listed with --all)")
continue
for i in group:
where = short(i["path"] or i.get("repo") or i.get("name", ""))
size = human(i["size"]) if i["size"] else "-"
why = (f"{i['branch']} · " if i.get("branch") else "") + i["note"]
lines.append(f" {i['id']:>3} {size:>9} {i['kind']:<15} {where}")
lines.append(f" {'':>3} {'':>9} {'':<15} {why}")
rec = sum(i["size"] for i in items if i["class"] == "REMOVE")
nd = sum(i["size"] for i in items if i["class"] == "NEEDS-DECISION")
lines.append(f"\nReclaimable: {human(rec)} recommended (REMOVE), up to {human(rec + nd)} with NEEDS-DECISION.")
return "\n".join(lines)
def cmd_scan(opts):
items = scan(opts)
STATE_DIR.mkdir(parents=True, exist_ok=True)
plan = {"version": VERSION, "created": dt.datetime.now().isoformat(timespec="seconds"),
"created_ts": NOW, "options": {k: v for k, v in vars(opts).items() if k != "func"},
"items": items}
PLAN_FILE.write_text(json.dumps(plan, indent=1))
if opts.json:
print(json.dumps(plan, indent=1))
return 0
print(f"agent-cleanup {VERSION} scan, {plan['created']}. Plan saved to {short(PLAN_FILE)}")
print(render(items, opts.all))
print("Next: apply --recommended or apply <ids> (add --dry-run to preview)")
return 0
# ---------------------------------------------------------------- apply
def parse_ids(tokens):
ids = set()
for tok in tokens:
for part in tok.split(","):
if not part:
continue
m = re.fullmatch(r"(\d+)(?:-(\d+))?", part)
if not m or (m.group(2) and int(m.group(2)) < int(m.group(1))):
raise ValueError(f"bad id or range: {part}")
ids.update(range(int(m.group(1)), int(m.group(2) or m.group(1)) + 1))
return ids
def recheck(planned, opts):
"""Current state of each planned item, re-derived the same way scan did."""
cwds = process_cwds()
fresh = {}
repos = {i["repo"] for i in planned if i["kind"] in ("worktree", "branch", "remote-branch")}
for r in repos:
if os.path.isdir(r):
for i in RepoScan(Path(r), opts, cwds).scan():
fresh[i["key"]] = i
for i in planned:
k, p = i["kind"], Path(i["path"]) if i["path"] else None
if k == "orphan-worktree" and p and p.is_dir() and is_orphan(p) and not in_use(str(p), cwds):
fresh[i["key"]] = dict(i, fingerprint=deep_fingerprint(p)[1])
elif k in ("archive", "backup") and p and (p.exists() or p.is_symlink()):
if not (p.is_dir() and in_use(str(p), cwds)):
fresh[i["key"]] = dict(i, fingerprint=deep_fingerprint(p)[1])
elif k in ("artifacts", "build-output") and p and p.is_dir():
for cur in artifact_items(p, i["is_git"], opts, cwds):
fresh[cur["key"]] = cur
elif k == "trash" and p and p.is_dir():
fresh[i["key"]] = dict(i, fingerprint=trash_fingerprint(p))
elif k in ("cache", "agent-data") and (p is None or p.exists()):
fresh[i["key"]] = i # rules are re-applied at delete time (age only grows)
return fresh
def execute(i, opts):
"""Perform one item's action. Returns a short result string."""
k, path, repo, br = i["kind"], i["path"], i.get("repo", ""), i.get("branch", "")
if opts.dry_run:
return "would " + describe(i)
if k == "worktree":
rescue = ""
head = i.get("head")
if not br and not i.get("registered_branch") and head and not git(
repo, "for-each-ref", "--count=1", "--contains", head): # detached, reachable from no ref
ref = f"refs/agent-cleanup/{Path(path).name}-{head[:10]}"
if not git_ok(repo, "update-ref", ref, head):
raise RuntimeError(f"could not save detached HEAD as {ref}; nothing removed")
rescue = f"; detached HEAD saved as {ref}"
args = ["git", "-C", repo, "worktree", "remove"]
if opts.force and i["class"] == "NEEDS-DECISION":
args.append("--force")
p = run(args + [path])
if not p or p.returncode != 0:
raise RuntimeError("git refused: " + (p.stderr.strip() if p else "git not found"))
if i.get("fingerprint", "").startswith("missing:"):
kept = f"; branch {i['registered_branch']} kept" if i.get("registered_branch") else ""
return "unregistered" + kept + rescue
if br and i["class"] == "REMOVE":
p = run(["git", "-C", repo, "branch", "-D", br])
if not p or p.returncode != 0:
return f"worktree removed; branch {br} kept ({p.stderr.strip() if p else 'git error'})"
return f"worktree removed, branch {br} deleted"
return "worktree removed" + (f"; branch {br} kept (has unmerged work)" if br else "") + rescue
if k == "branch":
p = run(["git", "-C", repo, "branch", "-D", br])
if not p or p.returncode != 0:
raise RuntimeError("git refused: " + (p.stderr.strip() if p else "git not found"))
return f"branch {br} deleted (was {i['head'][:10]})"
if k == "remote-branch": # the lease refuses if origin moved since the scan
p = run(["git", "-C", repo, "push", f"--force-with-lease=refs/heads/{br}:{i['fingerprint']}",
"origin", f":refs/heads/{br}"], timeout=120)
if not p or p.returncode != 0:
raise RuntimeError("push refused: " + (p.stderr.strip() if p else "git not found"))
return f"origin/{br} deleted"
if k in ("artifacts", "build-output"):
for d in i["paths"]:
if os.path.exists(d):
safe_rmtree(Path(d))
return f"deleted {len(i['paths'])} dir(s)"
if k in ("orphan-worktree", "archive", "backup"):
safe_rmtree(Path(path))
return "deleted"
if k == "cache":
if i["command"]:
p = run(i["command"], cwd=str(HOME), timeout=1800)
if not p or p.returncode != 0:
raise RuntimeError(f"`{' '.join(i['command'])}` failed: " + (p.stderr.strip()[-300:] if p else ""))
return f"ran `{' '.join(i['command'])}`"
for child in Path(path).iterdir():
safe_rmtree(child)
return "emptied"
if k == "agent-data":
n = 0
for target, _ in list(prunable(Path(path), i["rule"], i["keep_days"])):
safe_rmtree(Path(target))
n += 1
for root, dirs, files in os.walk(path, topdown=False):
if root != path and not dirs and not files:
try:
os.rmdir(root)
except OSError:
pass
return f"deleted {n} item(s) older than {i['keep_days']}d"
if k == "trash":
for e in trash_entries(Path(path)):
safe_rmtree(e)
return "trash emptied"
raise RuntimeError(f"no action for kind {k}")
def describe(i):
k = i["kind"]
return {
"worktree": f"git worktree remove {short(i['path'])}" + (" + delete branch " + i["branch"]
if i.get("branch") and i["class"] == "REMOVE" else ""),
"branch": f"git branch -D {i.get('branch')}",
"remote-branch": f"git push origin --delete {i.get('branch')} (with lease)",
"artifacts": "delete " + ", ".join(short(p) for p in i.get("paths", [])),
"build-output": "delete " + ", ".join(short(p) for p in i.get("paths", [])),
"cache": "run " + (" ".join(i.get("command") or []) or f"empty {short(i['path'])}"),
"agent-data": f"delete {short(i['path'])} entries older than {i.get('keep_days')}d",
"trash": f"empty {short(i['path'])}",
}.get(k, f"delete {short(i['path'])}")
def cmd_apply(opts):
if not PLAN_FILE.exists():
print("No plan found. Run `scan` first.", file=sys.stderr)
return 2
plan = json.loads(PLAN_FILE.read_text())
age_h = (time.time() - plan.get("created_ts", 0)) / 3600
if age_h > PLAN_MAX_AGE_HOURS:
print(f"The plan is {age_h:.0f}h old. Run `scan` again first.", file=sys.stderr)
return 2
items = plan["items"]
o = plan["options"]
print(f"Plan from {plan['created']}: repos {', '.join(short(r) for r in o.get('repo') or []) or '-'}, "
f"roots {', '.join(short(r) for r in o.get('root') or []) or '-'}")
if opts.recommended:
chosen = [i for i in items if i["class"] == "REMOVE"
and (i["kind"] != "remote-branch" or opts.remote)]
else:
try:
ids = parse_ids(opts.ids)
except ValueError as e:
print(e, file=sys.stderr)
return 2
unknown = ids - {i["id"] for i in items}
if unknown:
print(f"Unknown id(s): {sorted(unknown)}", file=sys.stderr)
return 2
chosen = [i for i in items if i["id"] in ids]
if not chosen:
print("Nothing selected.")
return 0
scan_opts = argparse.Namespace(**o)
fresh = recheck(chosen, scan_opts)
STATE_DIR.mkdir(parents=True, exist_ok=True)
freed, failures = 0, 0
# Worktrees before their branches; branches before remote branches.
rank = {"worktree": 0, "branch": 1, "remote-branch": 2}
for i in sorted(chosen, key=lambda x: rank.get(x["kind"], 3)):
label = f"#{i['id']} {i['kind']} {short(i['path']) or i.get('branch', '')}".rstrip()
cur = fresh.get(i["key"])
if i["class"] in ("KEEP-ACTIVE", "SKIP"):
result, ok = f"refused: class {i['class']} is never acted on", False
elif i["kind"] == "remote-branch" and not opts.remote:
result, ok = "refused: deleting branches on origin needs --remote", False
elif cur is None:
result, ok = "skipped: no longer present or now in use", False
elif cur["class"] != i["class"] or cur.get("fingerprint") != i.get("fingerprint"):
result, ok = f"skipped: changed since scan (now {cur['class']}: {cur['note']})", False
else:
if "paths" in i: # only dirs that still qualify now
i = dict(i, paths=[p for p in i["paths"] if p in cur["paths"]])
try:
result, ok = execute(i, opts), True
except Exception as e: # report and continue with the rest
result, ok = f"failed: {e}", False
if ok and not opts.dry_run:
if i["kind"] in ("cache", "agent-data", "trash"):
freed += max(i["size"] - (du(i["path"]) if i["path"] else 0), 0)
else:
freed += i["size"]
failures += not ok
print(f"{label}: {result}")
if not opts.dry_run:
with LOG_FILE.open("a") as f:
f.write(json.dumps({"at": dt.datetime.now().isoformat(timespec="seconds"), "ok": ok,
"result": result, "item": i}) + "\n")
if not opts.dry_run:
print(f"\nFreed about {human(freed)}. {failures} item(s) not applied. Log: {short(LOG_FILE)}")
return 1 if failures else 0
# ---------------------------------------------------------------- cli
def main(argv=None):
ap = argparse.ArgumentParser(prog="agent_cleanup.py", description=__doc__.split("\n\n")[0],
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog=__doc__.split("\n\n", 1)[1])
ap.add_argument("--version", action="version", version=VERSION)
sub = ap.add_subparsers(dest="cmd", required=True)
s = sub.add_parser("scan", help="read-only inventory; saves a numbered plan")
s.add_argument("--repo", action="append", default=[],
help="repository to inventory (default: the one containing the current directory)")
s.add_argument("--root", action="append", default=[],
help="folder of projects to sweep for repos, artifacts, archives and backups (repeatable)")
s.add_argument("--agent-root", action="append", default=[], help="extra agent worktree folder")
s.add_argument("--only", type=lambda v: v.split(","), help=f"comma list from {','.join(CATEGORIES)}")
s.add_argument("--base", help="base branch for every repo (default: origin/HEAD per repo)")
s.add_argument("--stale-days", type=int, default=14, help="untouched this long counts as stale (14)")
s.add_argument("--keep-days", type=int, default=30, help="agent logs newer than this are kept (30)")
s.add_argument("--min-size", type=parse_size, default=parse_size("20M"),
help="hide storage items smaller than this (20M)")
s.add_argument("--depth", type=int, default=3, help="how deep to look under each --root (3)")
s.add_argument("--fetch", action="store_true", help="git fetch --prune each repo first")
s.add_argument("--remote", action="store_true", help="also offer deleting merged branches on origin")
s.add_argument("--all", action="store_true", help="also list KEEP-ACTIVE and SKIP items")
s.add_argument("--json", action="store_true", help="print the plan as JSON")
s.set_defaults(func=cmd_scan)
a = sub.add_parser("apply", help="act on plan items after re-checking them")
a.add_argument("ids", nargs="*", help="item ids from the last scan: 3 5 7-9 or 3,5,7-9")
a.add_argument("--recommended", action="store_true", help="every REMOVE item (remote branches need --remote)")
a.add_argument("--remote", action="store_true", help="allow deleting the chosen branches on origin")
a.add_argument("--dry-run", action="store_true", help="show what would happen")
a.add_argument("--force", action="store_true",
help="allow `git worktree remove --force` on NEEDS-DECISION worktrees (discards their changes)")
a.set_defaults(func=cmd_apply)
opts = ap.parse_args(argv)
if opts.cmd == "scan" and opts.only:
bad = set(opts.only) - set(CATEGORIES)
if bad:
ap.error(f"unknown --only categories: {', '.join(sorted(bad))}")
if opts.cmd == "scan" and not opts.repo and not opts.root:
here = git(os.getcwd(), "rev-parse", "--show-toplevel")
if here:
opts.repo = [here]
if opts.cmd == "apply" and not opts.ids and not opts.recommended:
ap.error("give item ids or --recommended")
if not shutil.which("git"):
ap.error("git is required")
return opts.func(opts)
if __name__ == "__main__":
sys.exit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |