Skip to content

Add worktree-cleanup - #22

Merged
geodro merged 2 commits into
lerd-env:mainfrom
bikramtuladhar:add-worktree-cleanup
Nov 16, 2026
Merged

geodro merged 2 commits into
lerd-env:mainfrom
bikramtuladhar:add-worktree-cleanup

Conversation

@bikramtuladhar

Copy link
Copy Markdown
Contributor

Plugin

What it does

Every worktree of a proxy site runs its own dev server, and a Laravel worktree can have its own database, so finished worktrees pile up and keep fseventsd busy. This plugin removes the finished ones: PR merged, PR closed, or a detached / no-PR HEAD that has been on a base branch for a day. It skips worktrees a process is sitting in or that lerd saw recent traffic on. Uncommitted changes are saved as a patch first, or the worktree is kept, depending on your settings. Every rule is a toggle on its dashboard page.

What it adds to Lerd

  • Dashboard page Worktree cleanup: settings, schedule, tool check, Preview (dry run), Clean up now.
  • Commands worktree-cleanup:run, :config, :schedule.
  • Site command Clean up finished worktrees.
  • MCP tool worktree-cleanup_run with a skill (dry run first).
  • One API endpoint (api, GET/POST, loopback_only) used by the page.
  • Notifications: one after a scheduled run removes something (can be turned off with NOTIFY).

What it reads, changes and sends

  • Reads: /api/sites; each site's git repo (git fetch origin, status, merge-base); DB_DATABASE from the site's and worktree's .env, only to tell whether the worktree has its own database; process working folders (ps, lsof) to skip worktrees in use.
  • Changes: removes finished worktrees through lerd worktree remove and drops a worktree's own database through lerd db:share; deletes leftover dependency-only folders in <site>/.claude/worktrees/; writes its settings, log and patches to its data folder. When the user runs schedule on (off by default), it writes ~/Library/LaunchAgents/sh.lerd.plugin.worktree-cleanup.plist; schedule off removes it.
  • Sends over the network: through the user's logged-in gh, PR lists for each site's origin repository and a commit-SHA PR search for detached HEADs, to GitHub. Only when the user runs it (or turns the schedule on).

Requirements

requires: [curl, jq, git, lsof], plus gh logged in, checked at run time because the dashboard's PATH has no Homebrew. lerd: ">=1.38", platforms: [macos] (the schedule uses launchd).

Images

The Worktree cleanup page

Notes for the reviewer

  • Term 9, the schedule: lerd has no periodic or "PR merged" event, so schedule on writes a user LaunchAgent outside the plugin's folders. It is off until the user turns it on. I'd rather lerd offered a periodic plugin hook (e.g. hooks: every: 1h); happy to drop the schedule if that is preferred.
  • Term 13, GitHub: PR state comes from the GitHub API via gh, the plugin's core function. Nothing is sent until the user runs it.

Checklist

  • The repository is public and has an open source license.
  • The README says what the plugin adds, reads, changes and sends.
  • plugin.yaml declares lerd as a lower bound, and platforms if it runs on only one.
  • Everything it runs is readable source in the commit (POSIX sh + one HTML page): no binaries, no minified code, nothing downloaded and run.
  • It asks for no privilege and writes only to its own folder, its data folder and the sites it is run against, changing Lerd only through its API. (Exception: the opt-in schedule's LaunchAgent, see notes.)
  • It reads no secrets it has no stated need for, and a site's .env only when the README says why.
  • Lerd's token never leaves the machine and is never written outside the plugin's data folder.
  • Hooks finish quickly and fail without leaving a site, service or database half changed. (No hooks.)
  • Nothing leaves the machine without an opt-in the user turns on, and there are no analytics, tracking, ads or mining.
  • Any notifications are declared in plugin.yaml and only tell the user something they need to know or act on.
  • Pages bundle their own assets, nothing loads from third-party servers, and page scripts talk only to the plugin's own endpoints.
  • Any service image comes from a public registry, pinned. (No services.)
  • No service or framework reuses a name. (None.)
  • The name, description and images describe what it actually does.
  • The images show the plugin itself, are mine to publish, and are at most 6, each a PNG, JPEG or WebP under 1 MB and at most 2560 px wide.

@geodro geodro left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The plugin reads well and the guards are thought through, two things stand in the way before it can be listed.

The schedule writes a LaunchAgent into ~/Library/LaunchAgents, outside the plugin's folders, which term 9 rules out. Lerd now has this built in (lerd-env/lerd#2554, merged, shipping in the next release): declare schedules: in plugin.yaml with a name, every and the script to run, and lerd runs it from its dashboard service once the user allows it, asked at install and again whenever the schedules change. A run gets LERD_SURFACE=schedule. To keep SCHEDULE_EVERY as a user setting, declare the shortest interval you offer, say 15m, and have the script skip runs until its own interval has passed. That lets bin/schedule, the launchctl calls and the plist go, and with a portable stat in place of stat -f nothing left is macOS only, so platforms can go too. It needs lerd: set to the release that ships schedules, since an older lerd ignores the key and would never run it.

The leftover folder cleanup deletes .env files under .claude/worktrees, which belong to another tool and can hold the only copy of a worktree's config. Please drop LEFTOVER_FOLDERS, or leave a folder alone when it holds a .env.

Smaller ones. The notification goes out after every applied run, Clean up now and terminal runs included, while the README says only after a scheduled run; checking for LERD_SURFACE=schedule fixes that. plugin.yaml lists no screenshots, so docs/page.png won't show on the plugin's card. The sites API already gives each worktree db_isolated, which saves reading both .env files.

@bikramtuladhar

Copy link
Copy Markdown
Contributor Author

Thanks! All addressed in 2baa74c: the schedule now uses schedules: (15m, skipping until SCHEDULE_EVERY passes) with lerd: ">=1.39", bin/schedule, launchctl and platforms are gone (portable find -mmin/ps -eo), LEFTOVER_FOLDERS is removed,
notifications fire only on LERD_SURFACE=schedule, screenshots lists docs/page.png, and the DB check uses db_isolated/db_database from /api/sites.

@geodro geodro left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the whole change from the last commit and ran it in a VM against lerd built from main: the dry run kept the right worktrees, the scheduled run removed only the landed one once allowed, hostile settings and site names went nowhere, and removing it left lerd's config and sites as they were. Three small things for a later update, none blocking. A lerd: ">=1.39" bound also lets the 1.39 betas 1 to 3 load it, which have no schedules yet, so it only runs by hand there. The page points at System > Plugins, but Plugins has its own rail item now. And a settings value with a line break in it gets half applied before the rest is refused. Thanks for turning this around so quickly.

@geodro
geodro merged commit 9f188c6 into lerd-env:main Nov 16, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants