# Herd Worktree

> Serves the current git worktree as a Laravel Herd site, rewrites its .env for the new host, and installs dependencies.

- Skill: `samuelpatro/herd-worktree` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add samuelpatro/herd-worktree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samuelpatro/herd-worktree/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra, AI & ML, Deployment & Release
- Tags: Bun, Composer, Env, Git Worktree, Herd, Laravel, Vite
- Author: samuelpatro (https://skillmd.com/u/samuelpatro)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/samuelpatro/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 link`s 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.