---
name: Move To Worktree
slug: move-to-worktree
category: DevOps
description: Move To Worktree parks a clean, pushed task branch in an issue-numbered nested worktree and returns the primary checkout to main. Use it after /start-task when opening a parallel lane and setting its per-worktree ports and dependencies.
github: "https://github.com/foyzulkarim/claude-lens/tree/main/.claude/skills/move-to-worktree"
language: TypeScript
stars: 245
forks: 31
install: "npx degit https://github.com/foyzulkarim/claude-lens/tree/main/.claude/skills/move-to-worktree ~/.claude/skills/move-to-worktree"
installs_to: ~/.claude/skills/move-to-worktree
source_path: .claude/skills/move-to-worktree/SKILL.md
collection_size: 3
category_size: 868
collection_url: "https://dirskills.com/collections/foyzulkarim/claude-lens"
added: 2026-09-03T06:03:39.408Z
last_synced: 2026-09-03T06:03:39.408Z
canonical_url: "https://dirskills.com/skills/move-to-worktree"
---

# Move To Worktree

Move To Worktree parks a clean, pushed task branch in an issue-numbered nested worktree and returns the primary checkout to main. Use it after /start-task when opening a parallel lane and setting its per-worktree ports and dependencies.

**Install:**

```bash
npx degit https://github.com/foyzulkarim/claude-lens/tree/main/.claude/skills/move-to-worktree ~/.claude/skills/move-to-worktree
```

## README

# Move-to-Worktree

Companion to `/start-task` for parallel Phase 4 lanes (see
`specs/claude-lens-phase4-parallelization.md`). `/start-task` leaves the primary
checkout *on* the new feature branch; this skill moves that branch into its own
worktree and puts the primary back on `main` — one worktree + one branch + one
Claude session per in-flight issue.

## Run (1 bash call)

```bash
bash {base_directory}/move-to-worktree.sh
```

No arguments — it operates on the branch currently checked out. The script:

1. Hard-stops unless run in the **primary checkout**, on a **task branch**
   (`{type}/{issue#}/{slug}`), with a **clean tree** and its matching `origin/` **upstream** set —
   i.e. exactly the state `/start-task` leaves behind.
2. Pushes any local-only commits, checks out and fast-forwards `main` (this must
   happen *before* the worktree is created — git refuses to check out a branch
   in two places).
3. `git worktree add .worktrees/<issue#> <branch>` — nested inside the repo root
   (gitignored), never a `../` sibling. The context file `specs/context/<issue#>.md`
   travels with the branch (it's committed).
4. Writes the lane's port block to `<worktree>/.env.local` (gitignored):
   `CLAUDE_LENS_PORT_BASE = 4128 + 10 × issue#` — backend = base, Vite = base+1,
   E2E = base+2, Storybook = base+3. Issue-derived, so lanes cannot collide.
5. Runs `npm ci` in the worktree (per-worktree `node_modules`; also wires
   the Husky pre-push hook so `npm run verify` gates pushes from this lane).

Non-zero exit → hard-stop, print stderr verbatim.

## Report

The script's summary block (worktree path, branch, ports), plus: *"Open a new
Claude session in the worktree and continue the pipeline there
(`/plan-architecture` / `/implement` → `/review` → `/commit` → PR with
`Closes #N`)."*

When the PR has squash-merged, `/finish-worktree <issue#>` (run back in the
primary) does the teardown.

## You Must NOT

- Run the underlying git commands yourself — the script owns all mutation.
- Stash, discard, or commit anything to satisfy the clean-tree check — hard-stop instead.
- Move a branch whose upstream is ahead or does not match `origin/<branch>`.
- Create the worktree while the primary is still on the feature branch.