git-wtclean 0.1.0__py3-none-any.whl

git_wtclean-0.1.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: git-wtclean
+Version: 0.1.0
+Summary: Clean up the git worktrees coding agents leave behind, without losing work
+Project-URL: Homepage, https://github.com/Ar9av/wtclean
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,cleanup,codex,git,worktree
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# wtclean
+
+Clean up the git worktrees your coding agents leave behind, without losing work.
+
+![wtclean demo](https://raw.githubusercontent.com/Ar9av/wtclean/main/screenshot.png)
+
+## The problem
+
+Claude Code, Codex, Cursor, Conductor and friends run each task in its own **git worktree**: a second checkout of your repo in another folder, on its own branch. That's what lets five agents work on one repo without stepping on each other.
+
+Nobody deletes them afterwards. The agent finishes, the PR merges, and the folder stays, with its own copy of `node_modules`, build output and `.venv`. On one machine after a few weeks:
+
+- **287 worktrees across 101 repos**, two repos with 140+ each
+- **54 GB** of disk, mostly duplicated dependencies
+- `git worktree list` too long to read, branch pickers full of dead branches
+- no way to tell which ones an agent is still using
+
+The obvious fixes don't work:
+
+| You try | What happens |
+|---|---|
+| `git worktree prune` | Only forgets worktrees whose folder is *already* deleted. Frees nothing. |
+| `rm -rf` the folders | Deletes uncommitted work, and any `.env` you copied in. Git's metadata is left dangling. |
+| `git worktree remove --force` | Same: `--force` is the flag that skips the "you have changes" check. |
+| Ask the agent to clean up | [It happens](https://mergify.com/blog/the-day-my-ai-agent-deleted-29-git-worktrees): an agent removed 29 active worktrees. |
+
+## What wtclean does
+
+It looks at every worktree and sorts it into one of three groups:
+
+- **REMOVE** if it's clean and either
+  - its branch is merged or the remote branch was deleted, and it's been idle for 24 hours, or
+  - it's unmerged and has been idle for 7 days. The folder is removed and the branch is kept.
+- **PRUNE** if the folder is already gone and git still lists it.
+- **KEEP** if it has uncommitted changes, is locked, has a process running inside it, was used recently, holds a `.env` the main checkout doesn't have, or is a detached checkout with unpushed commits.
+
+It's a dry run until you add `--apply`.
+
+### Why nothing gets lost
+
+- Removal uses plain `git worktree remove`. Git itself refuses to delete a worktree with changes.
+- A branch is only deleted with `git branch -d`, which refuses unmerged work. Removing the folder of an unmerged branch keeps every commit, and `git worktree add <path> <branch>` brings it back.
+- What does get deleted is ignored stuff: `node_modules`, build output, caches. That's the disk you get back. Ignored `.env` files are checked first, and a worktree is kept if its `.env` differs from the main checkout's.
+
+## Install
+
+```bash
+pipx install git-wtclean      # or: uv tool install git-wtclean / pip install git-wtclean
+```
+
+That gives you `wtclean`, and `git wtclean` works too. Needs git and Python 3.9+, macOS or Linux.
+
+No pip? It's one file:
+
+```bash
+mkdir -p ~/.local/bin
+curl -fsSL https://raw.githubusercontent.com/Ar9av/wtclean/main/git_wtclean.py -o ~/.local/bin/wtclean
+chmod +x ~/.local/bin/wtclean
+```
+
+If `wtclean` isn't found afterwards, add `export PATH="$HOME/.local/bin:$PATH"` to your `~/.zshrc` or `~/.bashrc`.
+
+## Use
+
+```bash
+wtclean                                  # what would go, in the repo you're in
+wtclean --scan ~/code                    # same, for every repo under ~/code
+wtclean --scan ~/code --fetch --apply    # refresh from remotes, then clean up
+```
+
+Want to see it before pointing it at real repos? Clone this repo and run `./demo.sh`. It builds a throwaway repo full of fake agent worktrees and runs wtclean on it.
+
+The first `--apply` on a big backlog can take several minutes, mostly deleting `node_modules`. It shows progress as it goes.
+
+## Options
+
+| Flag | Default | |
+|------|---------|--|
+| `--scan DIR` | | find repos under DIR (3 levels deep) |
+| `--apply` | off | actually remove |
+| `--fetch` | off | `git fetch --prune` first, so merged / deleted-on-remote is current |
+| `--idle H` | 24 | hours untouched before a merged worktree is removed |
+| `--stale D` | 7 | days untouched before an unmerged worktree is removed |
+| `--all` | off | also list KEEP rows, with the reason |
+| `--json` | off | machine-readable output |
+
+## Use it from your agents
+
+Paste this into `AGENTS.md` or `CLAUDE.md`:
+
+```
+Worktrees: lock the worktree you work in with
+`git worktree lock --reason "<task>" <path>` and unlock it when you finish.
+To check for leftovers, run `wtclean --json`. Only run `wtclean --apply` when the user asks.
+```
+
+`--json` returns one object per worktree: `path`, `branch`, `action` (`remove` / `prune` / `keep`), `reason`, `idle_h`.
+
+Or run it on a schedule. This crontab line cleans up every Monday at 9am:
+
+```
+0 9 * * 1  ~/.local/bin/wtclean --scan ~/code --fetch --apply >> ~/.wtclean.log 2>&1
+```
+
+## Development
+
+```bash
+./test.sh   # builds a scratch repo covering every case and checks each verdict
+```
+
+One file, standard library only. MIT licensed.

git_wtclean-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+git_wtclean.py,sha256=XcqKu5RKfcl8VW7nswhFb1wHFWcSCosEIOp4dxRuV1U,10475
+git_wtclean-0.1.0.dist-info/METADATA,sha256=UTiPu7e7QkJra6exllcRbFOxY2WcD1UGe_h54jr8wJs,5489
+git_wtclean-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+git_wtclean-0.1.0.dist-info/entry_points.txt,sha256=KAcDFnBU8DAAImvFwQ8h_olVcS1_cFkrkdFGBGg4tm4,76
+git_wtclean-0.1.0.dist-info/licenses/LICENSE,sha256=cMeaBzF1RXlP4wmBGUnB5jf7TPj7e_zdw2WMJedYsBk,1062
+git_wtclean-0.1.0.dist-info/RECORD,,

git_wtclean-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

git_wtclean-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+git-wtclean = git_wtclean:main
+wtclean = git_wtclean:main

git_wtclean-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ar9av
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_wtclean.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""wtclean - find and remove dead git worktrees left behind by coding agents.
+
+Dry-run by default. Removal goes through `git worktree remove` (no --force),
+so git itself refuses anything dirty. Branches are only deleted with
+`git branch -d`, which refuses unmerged work. Nothing is ever rm -rf'd.
+
+  wtclean                      # report for the repo you're in
+  wtclean ~/code/a ~/code/b    # several repos
+  wtclean --scan ~/code        # every repo under a dir (depth 3)
+  wtclean --apply              # actually remove the REMOVE rows
+  wtclean --json               # machine-readable, for agents
+"""
+__version__ = "0.1.0"
+
+import argparse, filecmp, json, os, shutil, subprocess, sys, time
+from concurrent.futures import ThreadPoolExecutor
+
+os.environ["GIT_OPTIONAL_LOCKS"] = "0"  # read-only scans must not rewrite indexes (that resets the idle clock)
+
+
+def git(cwd, *args):
+    r = subprocess.run(["git", "-C", cwd, *args], capture_output=True, text=True)
+    return r.returncode, r.stdout.strip(), r.stderr.strip()
+
+
+def worktrees(repo):
+    _, out, _ = git(repo, "worktree", "list", "--porcelain")
+    wts, cur = [], {}
+    for line in out.splitlines() + [""]:
+        if not line:
+            if cur:
+                wts.append(cur)
+            cur = {}
+            continue
+        k, _, v = line.partition(" ")
+        cur[k] = v or True
+    return wts  # first entry is the main worktree
+
+
+def default_branch(repo):
+    rc, out, _ = git(repo, "symbolic-ref", "--short", "refs/remotes/origin/HEAD")
+    if rc == 0:
+        return out
+    for b in ("origin/main", "origin/master", "main", "master"):
+        if git(repo, "rev-parse", "--verify", "-q", b)[0] == 0:
+            return b
+    return "HEAD"
+
+
+def idle_hours(repo, path):
+    # last activity = newest of the worktree's index / HEAD in its git admin dir
+    _, gitdir, _ = git(path, "rev-parse", "--absolute-git-dir")
+    ts = [os.path.getmtime(os.path.join(gitdir, f))
+          for f in ("index", "HEAD", "logs/HEAD") if os.path.exists(os.path.join(gitdir, f))]
+    return (time.time() - max(ts)) / 3600 if ts else 1e9
+
+
+def busy_dirs():
+    # cwd of every running process: a dev server, shell or agent sitting in a worktree means it's in use
+    try:
+        r = subprocess.run(["lsof", "-a", "-d", "cwd", "-Fn"], capture_output=True, text=True)
+        return {l[1:] for l in r.stdout.splitlines() if l.startswith("n")}
+    except FileNotFoundError:  # Linux without lsof
+        out = set()
+        for pid in os.listdir("/proc") if os.path.isdir("/proc") else []:
+            try:
+                out.add(os.readlink(f"/proc/{pid}/cwd"))
+            except OSError:
+                pass
+        return out
+
+
+BUSY = None
+
+
+def unique_secrets(path, main):
+    # ignored .env-style files are deleted with the worktree; flag ones the main checkout doesn't have
+    out = []
+    for d, subs, files in os.walk(path):
+        subs[:] = [s for s in subs if s not in (".git", "node_modules", ".venv", "venv")]
+        if d[len(path):].count(os.sep) >= 3:
+            subs[:] = []
+        for f in files:
+            if f.startswith(".env") and not f.endswith((".example", ".sample", ".template")):
+                rel = os.path.relpath(os.path.join(d, f), path)
+                twin = os.path.join(main, rel)
+                if not (os.path.isfile(twin) and filecmp.cmp(twin, os.path.join(d, f), shallow=False)):
+                    out.append(rel)
+    return out
+
+
+def classify(repo, wt, base, gone, idle_min, stale_h):
+    path, sha = wt["worktree"], wt.get("HEAD", "")
+    branch = wt.get("branch", "").removeprefix("refs/heads/") or None
+    row = {"repo": repo, "path": path, "branch": branch or f"(detached {sha[:7]})",
+           "action": "keep", "reason": ""}
+    if wt.get("prunable") or not os.path.isdir(path):
+        return {**row, "action": "prune", "reason": "dir missing"}
+    if wt.get("locked"):
+        return {**row, "reason": "locked"}
+    if any(b == path or b.startswith(path + "/") for b in BUSY):
+        return {**row, "reason": "process running here"}
+    idle = idle_hours(repo, path)  # before status: status may rewrite the index and reset the clock
+    row["idle_h"] = round(idle)
+    rc, dirty, _ = git(path, "status", "--porcelain")
+    if rc or dirty:
+        return {**row, "reason": f"uncommitted changes ({plural(len(dirty.splitlines()), 'file')})" if not rc else "status failed"}
+    if idle < idle_min:
+        return {**row, "reason": f"active {idle:.0f}h ago"}
+    secrets = unique_secrets(path, repo)
+    if secrets:
+        return {**row, "reason": f"has {secrets[0]} not in main checkout"}
+    merged = git(repo, "merge-base", "--is-ancestor", sha, base)[0] == 0
+    if merged:
+        return {**row, "action": "remove", "reason": f"merged into {base}", "del_branch": bool(branch)}
+    if branch in gone:
+        return {**row, "action": "remove", "reason": "remote branch gone (PR closed/squashed)"}
+    if not branch:  # detached: only safe if its commits live on some remote ref
+        _, on_remote, _ = git(repo, "for-each-ref", "--contains", sha, "--count=1", "refs/remotes")
+        if not on_remote:
+            return {**row, "reason": "detached with unpushed commits"}
+    # clean, idle, unmerged: removing the worktree is lossless, the branch keeps the commits,
+    # but in-flight work gets a longer grace period than merged/abandoned branches
+    if idle < stale_h:
+        return {**row, "reason": f"unmerged, idle {idle / 24:.0f}d < --stale"}
+    return {**row, "action": "remove", "reason": f"idle {idle / 24:.0f}d, branch kept"}
+
+
+def scan_repo(repo, idle_min, stale_h):
+    wts = worktrees(repo)
+    if not wts:
+        return []
+    main = wts[0]["worktree"]
+    base = default_branch(main)
+    _, refs, _ = git(main, "for-each-ref", "--format=%(refname:short)|%(upstream:track)", "refs/heads")
+    gone = {l.split("|")[0] for l in refs.splitlines() if "[gone]" in l}
+    with ThreadPoolExecutor(16) as ex:
+        return list(ex.map(lambda w: classify(main, w, base, gone, idle_min, stale_h), wts[1:]))
+
+
+def find_repos(root, depth=3):
+    root = os.path.expanduser(root)
+    for d, subs, _ in os.walk(root):
+        if ".git" in subs and os.path.isdir(os.path.join(d, ".git")):  # skip linked worktrees (.git file)
+            yield d
+            subs[:] = []
+        elif d[len(root):].count(os.sep) >= depth:
+            subs[:] = []
+        else:
+            subs[:] = [s for s in subs if not s.startswith(".") and s != "node_modules"]
+
+
+def plural(n, word):
+    return f"{n} {word}{'' if n == 1 else 's'}"
+
+
+def apply(rows):
+    todo = [r for r in rows if r["action"] == "remove"]
+    for i, r in enumerate(todo, 1):
+        if sys.stderr.isatty():  # big node_modules trees take a while; show we're alive
+            line = f"[{i}/{len(todo)}] removing {r['path'].replace(os.path.expanduser('~'), '~')}"
+            sys.stderr.write("\r\033[K" + line[:shutil.get_terminal_size().columns - 1])
+            sys.stderr.flush()
+        rc, _, err = git(r["repo"], "worktree", "remove", r["path"])
+        r["result"] = "removed" if rc == 0 else f"failed: {err.splitlines()[-1] if err else rc}"
+        if rc == 0 and r.get("del_branch") and git(r["repo"], "branch", "-d", r["branch"])[0] == 0:
+            r["result"] += " +branch"
+    if todo and sys.stderr.isatty():
+        sys.stderr.write("\r\033[K")
+    for repo in {r["repo"] for r in rows}:
+        git(repo, "worktree", "prune")
+    for r in rows:
+        if r["action"] == "prune":
+            r["result"] = "pruned"
+
+
+def main():
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"wtclean {__version__}")
+    p.add_argument("repos", nargs="*", help="repo paths (default: current repo)")
+    p.add_argument("--scan", metavar="DIR", help="find repos under DIR")
+    p.add_argument("--idle", type=float, default=24, help="hours untouched before a worktree counts as dead (default 24)")
+    p.add_argument("--stale", type=float, default=7, help="days idle before an UNMERGED worktree counts as dead (default 7)")
+    p.add_argument("--apply", action="store_true", help="remove the REMOVE rows (default: dry run)")
+    p.add_argument("--fetch", action="store_true", help="git fetch --prune first, so merged/gone is current")
+    p.add_argument("--json", action="store_true", help="print JSON (for agents)")
+    p.add_argument("--all", action="store_true", help="also list KEEP rows")
+    a = p.parse_args()
+    global BUSY
+    BUSY = busy_dirs()
+
+    repos = list(a.repos) or ([] if a.scan else ["."])
+    if a.scan:
+        repos += list(find_repos(a.scan))
+    found = set()
+    for r in repos:
+        rc, d, _ = git(os.path.expanduser(r), "rev-parse", "--path-format=absolute", "--git-common-dir")
+        if rc:
+            sys.exit(f"wtclean: {r} is not a git repo. Run it inside a repo, or use --scan DIR.")
+        found.add(d.removesuffix("/.git"))
+    repos = found
+    if a.fetch:
+        with ThreadPoolExecutor(8) as ex:
+            list(ex.map(lambda r: git(r, "fetch", "--prune", "-q"), repos))
+    rows = [row for r in sorted(repos) for row in scan_repo(r, a.idle, a.stale * 24)]
+    if a.apply:
+        apply(rows)
+
+    if a.json:
+        json.dump(rows, sys.stdout, indent=1)
+        print()
+        return
+    home = os.path.expanduser("~")
+    color = sys.stdout.isatty()
+    paint = {"remove": "\033[31m", "prune": "\033[33m", "keep": "\033[32m"}
+    shown = [r for r in rows if r["action"] != "keep" or a.all]
+    pw = max([len(r["path"].replace(home, "~")) for r in shown] + [10])
+    bw = max([len(r["branch"][:38]) for r in shown] + [6])
+    for r in shown:
+        tag = r["action"].upper().ljust(6)
+        if color:
+            tag = paint[r["action"]] + tag + "\033[0m"
+        print(f"{tag} {r['path'].replace(home, '~'):<{pw}}  {r['branch'][:38]:<{bw}}   {r['reason']}"
+              + (f"  -> {r['result']}" if "result" in r else ""))
+    n = {k: sum(r["action"] == k for r in rows) for k in ("remove", "prune", "keep")}
+    verb = "removed" if a.apply else "would remove"
+    print(f"\n{plural(len(rows), 'worktree')} in {plural(len(repos), 'repo')}: {verb} {n['remove']}, "
+          f"prune {n['prune']}, keep {n['keep']}" + ("" if a.apply else "  (dry run: add --apply to do it)"))
+    if any(r.get("result", "").startswith("failed") for r in rows):
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()