Herd Worktree

Herd a worktree

The agents view already isolates each background agent in its own git worktree under .claude/worktrees/<name>. This skill adds the Laravel-runnable layer the harness does not: a Herd .test host, a .env rewritten for that host, and installed dependencies. Run it from inside the worktree you want to serve.

What it does (on --apply)

1. Derives a site name <project>-<worktree> and host http://<site>.test.
2. Copies .env from the main checkout if the worktree doesn't already have one (worktrees created after first run get .env automatically, see below).
3. Rewrites APP_URL, SESSION_DOMAIN, appends to SANCTUM_STATEFUL_DOMAINS (only if that key exists), sets SESSION_SECURE_COOKIE=false, and sets VITE_DEV_URL=http://localhost:<port> with a per-worktree port (5176-5275, stable per worktree name) so multiple worktree dev servers can run at once. Laravel reads VITE_DEV_URL from this root .env; Vite loads env from its own dir, so the skill also writes .env.local (same VITE_DEV_URL + APP_URL) into every tracked Vite-config dir (e.g. themes/dr/). --down removes them.
4. Adds .env to the main checkout's .worktreeinclude so future worktrees get it copied in automatically (the cheap, always-on half of the setup).
5. herd link <site> — HTTP only (no herd secure, to match Vite).
6. composer install (if composer.json) and bun install (if package.json).
7. php artisan config:clear + cache:clear (if artisan).

It does not start Vite. Start the frontend yourself with bun run dev when you need it; it binds to this worktree's port automatically (vite.config.ts reads VITE_DEV_URL from the .env.local the skill wrote), and the PHP/Twig side loads dev assets from the same URL via the root .env.

Steps

Run from inside the worktree. The skill is idempotent and safe to re-run, so apply directly (no need to preview first):

bun ~/.claude/skills/herd-worktree/herd.ts --apply

Then open the printed http://<site>.test. That single command copies/rewrites .env, writes per-worktree .env.local for each Vite project, herd links the site, and installs dependencies.

Optional variants:

bun ~/.claude/skills/herd-worktree/herd.ts            # plan only (changes nothing)
bun ~/.claude/skills/herd-worktree/herd.ts --down     # tear down before removing the worktree
bun ~/.claude/skills/herd-worktree/herd.ts --apply --force   # run outside .claude/worktrees/

Notes

• Guard: refuses to run outside .claude/worktrees/ unless you pass --force. This prevents it from ever touching your main checkout's .env or Herd site.
• Idempotent: re-running --apply is safe (no duplicate Sanctum domains, etc.).
• This is the on-demand half of a hybrid setup. The always-on half is the .env -> .worktreeinclude copy, which needs no skill once seeded.
• Source of truth lives in the .claude backup repo at skills/herd-worktree/; it is copied to ~/.claude/skills/herd-worktree/ to be runnable. Re-run the sync after editing.