# Worktree Bootstrap

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-jakerains-agentskills-worktree-bootstrap`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jakerains](https://agentstack.voostack.com/s/jakerains)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jakerains](https://github.com/jakerains)
- **Source:** https://github.com/jakerains/AgentSkills/tree/main/skills/worktree-bootstrap

## Install

```sh
agentstack add skill-jakerains-agentskills-worktree-bootstrap
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# worktree-bootstrap

Make a git worktree run its dev server **exactly like the active trunk** — in one command. Project-agnostic: works for any JavaScript/TypeScript repo on macOS, Linux, or WSL.

## Two modes (auto-detected)

Run the same script anywhere — it detects where you are and does the right thing:

- **Inside a linked worktree** → **bootstrap** it: catch up to the trunk, copy env, install deps, check the Next.js pins. (The common case — the rest of this doc.)
- **In the primary checkout** (not a worktree) → **prep** the current branch for worktrees: audit the branch-level things every future worktree *inherits* — a `.worktreeinclude` file (so new worktrees get gitignored secrets at creation) and the `turbopack.root` / `allowedDevOrigins` pins — and report what's missing. **When the script runs in prep mode, apply its recommendations:** create or extend `.worktreeinclude` (safe + additive — show the user what you're adding), and propose the `next.config` pins for confirmation (they're source code). It's a one-time "make this branch worktree-ready" pass.

## Why this exists

A linked worktree is pinned to its **own dedicated branch** (git won't let two worktrees share one), and that branch is **frozen at creation** — it never advances, so every commit on the trunk leaves the worktree silently behind ("missing commits"). On top of that, `git worktree add` (and `claude --worktree`) only check out **tracked** files, so a new worktree is also missing the *gitignored* things a dev server needs:

- **Behind the trunk** → the worktree's branch predates recent commits (config pins, lockfile changes, fixes). This skill **fast-forwards it to the trunk first**, so every later step runs on the final tree.
- **`.env.local` / `.env`** → the app crashes at runtime because a required env var is undefined (a database URL, an API key, etc.).
- **`node_modules`** → `pnpm run dev` fails with `next: command not found` (pnpm won't climb to the parent's `node_modules`).

And for **Next.js**, a worktree nested inside another repo can make Turbopack mis-resolve its workspace root to the parent and watch two dependency trees at once — which can exhaust memory and **hard-freeze the machine**. The fix is a one-line source pin (`turbopack.root`); this skill detects when it's missing — though usually it arrives automatically with the catch-up.

## How to run it

Run the bundled script — it auto-detects worktree vs primary checkout:

```bash
bash scripts/setup-worktree.sh
```

(Use the absolute path to this skill's `scripts/setup-worktree.sh` if you're not in the skill directory.) Then relay its summary to the user — and in **prep mode**, apply the recommendations it prints (see "Two modes"). The script is **idempotent** — re-running when already current is a clean no-op. Its only history mutation is a strict fast-forward (`git merge --ff-only`) to the local trunk; it never does a non-ff merge, rebase, reset, force, fetch, or pull, and it **skips and continues** whenever a fast-forward isn't safe.

## What it does

1. **Catch up to trunk** — fast-forwards the worktree to the **active trunk** (the branch the primary worktree has checked out, resolved dynamically from `git worktree list` — never hardcoded) via `git merge --ff-only`, so dep-install and the config checks below all run on the final tree. It **skips and continues** (never aborts, never auto-resolves) when the trunk can't be resolved, this worktree *is* the trunk, the tree has uncommitted tracked changes, or the branch has **diverged** (local commits not on the trunk — it tells you to `git rebase` manually).
2. **Env** — copies every gitignored top-level `.env*` file from the **main** checkout into the worktree, only if missing (never overwrites, never prints contents). *(On Claude Code, a `.worktreeinclude` file at the repo root copies gitignored files into worktrees at creation time — for `--worktree`, subagent, and parallel sessions — so this step is the portable fallback and a no-op when they're already present.)*
3. **Dependencies** — if `node_modules` is absent, detects the package manager from the lockfile (`pnpm-lock.yaml` → pnpm, `package-lock.json` → npm, `yarn.lock` → yarn, `bun.lockb` → bun) and runs the matching install — against the *caught-up* lockfile. With pnpm's shared global store this is typically a few seconds.
4. **Next.js workspace-root check** (read-only) — if a `next.config.*` exists without a `turbopack.root` pin **and** there's a lockfile above the worktree, it warns and prints the fix:
   ```ts
   // next.config.ts — inside nextConfig
   turbopack: { root: import.meta.dirname },
   ```
5. **portless dev-origin check** (read-only) — if `next.config.*` exists and the `portless` CLI is installed, it verifies `allowedDevOrigins` covers portless's multi-label `..localhost` host. Next's default `*.localhost` is a *single-label* wildcard, so a two-label portless host gets its dev/HMR requests blocked; if uncovered, it advises the recursive wildcard:
   ```ts
   // next.config.ts — inside nextConfig
   allowedDevOrigins: ["**.localhost"],
   ```

## Why a worktree can be behind

A worktree's branch is frozen at creation, and `claude --worktree` may branch it from the **fork-point** of `main` and your trunk rather than the trunk's current tip — so it predates recent commits, including the Turbopack pins. Step 1 handles this automatically by fast-forwarding to the trunk. It only **can't** when your worktree has diverged (its own commits) or has uncommitted changes — then it tells you exactly what to run.

## The one thing it can't do for you

If your branch has **diverged** from the trunk (you've committed work the trunk doesn't have), step 1 won't fast-forward — that would need a real merge or rebase, which can conflict, so it leaves that to you (`git rebase `). And the config pins themselves (`turbopack.root`, `allowedDevOrigins`) are **source code**: if they're genuinely missing from the trunk, add them once on the trunk — every worktree then inherits them via the catch-up.

> Note for monorepos: drop the `turbopack.root: import.meta.dirname` pin when the app lives inside a monorepo — there the root must be the monorepo root, not the app directory.

## Safety

Resolves all paths and the trunk via git (`git rev-parse`, `git worktree list`) — never from user input. Quotes every path, uses no `eval`, and only ever runs `git`, `cp`, and the detected package-manager install. The only history-changing operation is a strict `git merge --ff-only` to a locally-resolved branch — no non-ff merge, rebase, reset, force, fetch, or pull. Env files are copied between two checkouts of the same repo on the same machine; their contents are never transmitted, printed, or logged.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jakerains](https://github.com/jakerains)
- **Source:** [jakerains/AgentSkills](https://github.com/jakerains/AgentSkills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jakerains-agentskills-worktree-bootstrap
- Seller: https://agentstack.voostack.com/s/jakerains
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.