git:20260714.2a3c4ed to git:20260926.e57a6cf

---

name: worktree

description: Create an isolated git worktree + branch + port for this session so concurrent kube-coder sessions and builds don't conflict. Use at the START of any change you want isolated, when two sessions touch the same repo, or before running a dev server/build that would collide on ports or output dirs. Also lists and tears down worktrees.

user-invocable: true

allowed-tools: Bash, Read

argument-hint: "[slug] | list | rm <slug> [--force] (default: new, slug from task id)"

---

kube-coder isolates sessions at the *terminal* level (each task gets its own

tmux session + `~/.claude-tasks/<id>/`) but everything still runs in the **same

`/home/dev` filesystem**. So two sessions on the same repo collide three ways:

- **git tree** — branch/checkout/index thrash, a dirty working tree

- **build output** — both write `./dist`, `./build`; Kaniko reads its context from the shared path

- **dev-server ports** — `EADDRINUSE` on `:3000` (ports are per-*pod*, not per-session)

This skill fixes all three for the current session with **no infra change**: it

gives you a dedicated `git worktree` (own checkout + branch) at a path outside

the repo, and leases a free port for any server you start. Worktrees share the

main clone's object store, so they're cheap on disk — only working files are

duplicated.

The helper is `worktree.sh` next to this file. Invoke it as

`bash "$CLAUDE_SKILL_DIR/worktree.sh" …` (or with its absolute path under

`/home/dev/kube-coder/.claude/skills/worktree/`).

## Start an isolated session (the common path)

Run from **inside the repo** you want to work on (`cd` there first). `$ARGUMENTS`

is an optional human slug; if omitted it derives one from the current task id

(`KC_TASK_ID`) or a random token, so it's always unique.

```bash

WT=/home/dev/kube-coder/.claude/skills/worktree/worktree.sh

eval "$(bash "$WT" new "$ARGUMENTS")" # creates worktree+branch+port, sets KC_WT / PORT

cd "$KC_WT" # <-- this cd PERSISTS across your Bash calls

```

After this, **do all work for the change from `$KC_WT`.** The human summary

(path / branch / port / preview URL) is printed to stderr — note the **port**,

because exported env vars do *not* survive between separate Bash tool calls (the

`cd` does). The worktree also records everything in `$KC_WT/.kc-worktree.json`,

so you can re-read the port later:

```bash

jq -r .port "$KC_WT/.kc-worktree.json" # or read .branch / .path

```

### What you get

- worktree dir: `/home/dev/.worktrees/<repo>/<slug>/`

- branch: `kc/<slug>` (branched from current HEAD, or a base-ref: `new <slug> <base>`)

## Running a dev server / preview

Bind the leased port explicitly (env doesn't persist between calls), then open

it through the app-proxy — no port config in the dashboard needed:

```bash

PORT=$(jq -r .port "$KC_WT/.kc-worktree.json")

cd "$KC_WT" && PORT=$PORT npm run dev # or: python -m http.server "$PORT", etc.

# preview at: /api/app-proxy/<port>/

```

## Builds

Because the worktree is its own path, `docker-build` (Kaniko) and local build

output (`./dist`, `./build`) no longer collide with other sessions. Run builds

with the worktree as context — e.g. `docker-build -t img:tag "$KC_WT"`.

## List / tear down

```bash

bash "$WT" list # worktrees + leased ports for the current repo

bash "$WT" rm <slug> # remove the worktree DIR; the branch is KEPT

bash "$WT" rm <slug> --force # also drop uncommitted changes in it

```

`rm` deliberately keeps `kc/<slug>` — that branch *is* your change. Push/PR it as

usual, then delete with the `git branch -D` line `rm` prints. `rm` refuses to

delete a dirty worktree unless you pass `--force`.

## Footguns

1. **Uncommitted work stays behind.** A worktree branches from **HEAD** (the

committed state). Anything uncommitted on your original checkout is *not*

carried in. Commit or stash first if you need it.

2. **`cd` persists, env does not.** In this harness the working directory

survives between Bash calls but exported vars don't. Rely on `cd "$KC_WT"`

and re-read the port from `.kc-worktree.json` when you need it; don't assume

`$PORT` is still set in a later call.

3. **Disk.** Worktrees share `.git`, but a fresh `node_modules` / `.venv` /

build tree per worktree is *not* shared and can fill the 20–50Gi PVC. Keep a

handful live at once; `rm` ones you're done with.

4. **One repo, one clone.** All worktrees for a repo register under that clone's

`.git/worktrees`. Don't `rm -rf` a worktree dir by hand — use `rm` (which runs

`git worktree remove` + `prune`) so git's bookkeeping stays consistent.

5. **Not for the boot-time kube-coder pull.** `start.sh` does

`git pull --ff-only origin main` on `/home/dev/kube-coder` at boot. Working in

a `kc/<slug>` worktree keeps `main` clean so that pull still fast-forwards —

which is the point. Don't check out `main` inside a worktree.

```bash

bash -n /home/dev/kube-coder/.claude/skills/worktree/worktree.sh

```