Skip to content
Skills Library
Programming · Learning & explanation

worktree-help

/worktree-help

Answer questions about the worktree toolkit: VSCode integration, gitignore, port offsets, env files, dependency installs, workflow tips. Use when user asks how worktrees work, "how do I open this in VSCode", "why is .env copied", "what about port collisions", "how do worktrees affect main repo", "worktree workflow", "show me the worktree FAQ", or any question about the setup. Also triggers for `/empire-git:worktree-help [question]`.

Repository
empire ↗
Licence
MIT
Last repository change
07.10.2026

Assessment and security

85/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content20 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Answer questions about the worktree toolkit: VSCode integration, gitignore, port offsets, env files, dependency installs, workflow tips. Use when user asks how worktrees work, "how do I open this in VSCode", "why is .env copied", "what about port collisions", "how do worktrees affect main repo", "worktree workflow", "show me the worktree FAQ", or any question about the setup. Also triggers for `/empire-git:worktree-help [question]`.

Triggers from the description

how do I open this in VSCodewhy is .env copiedwhat about port collisionshow do worktrees affect main repoworktree workflowshow me the worktree FAQ

Arguments

/worktree-help [question]
Original author description

Answer questions about the worktree toolkit: VSCode integration, gitignore, port offsets, env files, dependency installs, workflow tips. Use when user asks how worktrees work, "how do I open this in VSCode", "why is .env copied", "what about port collisions", "how do worktrees affect main repo", "worktree workflow", "show me the worktree FAQ", or any question about the setup. Also triggers for `/empire-git:worktree-help [question]`.

How it works

  1. Overview (print when $ARGUMENTS is empty)
  2. FAQ
Original SKILL.md headings · 74 lines, 901 words
SKILL.md preview
---
name: worktree-help
description: >
  Answer questions about the worktree toolkit: VSCode integration, gitignore,
  port offsets, env files, dependency installs, workflow tips. Use when user
  asks how worktrees work, "how do I open this in VSCode", "why is .env
  copied", "what about port collisions", "how do worktrees affect main repo",
  "worktree workflow", "show me the worktree FAQ", or any question about the
  setup. Also triggers for `/empire-git:worktree-help [question]`.
compatibility: Requires git. Runs in Claude Code and OpenAI Codex.
model: haiku
allowed-tools: Bash Read Glob Grep
argument-hint: "[question]"
---

# Worktree Help

`$ARGUMENTS` is the user's question. If empty, MUST print the **Overview** section below byte-for-byte verbatim — do not paraphrase, summarize, or reorder. Otherwise, answer their question using the **FAQ** section as your primary reference, falling back to your knowledge of git worktrees and this plugin's setup.

Keep answers concise and practical. When relevant, include `code .claude/worktrees/<branch-dir>` — it's the single most useful tip for new users.

---

## Overview (print when `$ARGUMENTS` is empty)

The empire worktree skills are a toolkit for running multiple branches of the same repo in parallel, each in its own isolated git worktree, with Claude Code skills that handle the lifecycle for you.

**Why it exists.** Switching branches mid-task is disruptive: you stash, rebuild, lose dev server state, and risk polluting one branch's `.env` with another's. Worktrees give each branch its own directory, dependencies, ports, and env — so you (or a Claude agent) can spin up a parallel task without touching what you're already working on. This plugin automates the boring parts: derived ports, copied env files, dependency installs, cleanup, and merge/close flows.

**Zero per-repo setup.** The plugin ships with `worktree-setup.sh`; skills invoke it via `${CLAUDE_PLUGIN_ROOT}/scripts/` on Claude Code and a bundled `scripts/` copy on other agents (e.g. Codex). Lockfiles are auto-detected (pnpm, npm, yarn, bun, uv, poetry, pipenv, bundler, cargo, go modules). The `.claude/worktrees` ignore entry is written to `.git/info/exclude`, never the repo's tracked `.gitignore`.

### Available skills

| Command                                                               | Purpose                                                   |
| --------------------------------------------------------------------- | --------------------------------------------------------- |
| `/empire-git:worktree-open [branch or description] [--base <branch>]` | Create or reopen a worktree (env, deps, ports handled)    |
| `/empire-git:worktree-list [--stale]`                                 | List active worktrees with branch, sync state, staleness  |
| `/empire-git:worktree-merge <branch> --into <target> [--no-close]`    | Local git merge of one branch into another                |
| `/empire-git:worktree-close [branch] [--push] [--force]`              | Push, remove the worktree, optionally delete the branch   |
| `/empire-git:worktree-cleanup [--dry-run]`                            | Batch cleanup of stale worktrees and orphaned branches    |
| `/empire-git:worktree-help [question]`                                | This help — ask any worktree question in natural language |

Ask `/empire-git:worktree-help <your question>` for anything specific (VSCode setup, ports, env files, merge strategy, etc.).

### Credits

Inspired by [`@thinkvelta/claude-worktree-tools`](https://github.com/ThinkVelta/claude-worktree-tools) (MIT).

---

## FAQ

**Q: How do I see a worktree in VSCode?**
Open it as its own window: `code .claude/worktrees/<branch-dir>`. The main repo's Source Control panel won't show worktree changes — that's by design (worktrees are excluded). Alternative: File → Add Folder to Workspace for a multi-root setup.

**Q: Why is `.claude/worktrees/` in `.git/info/exclude`?**
Required. Worktrees are git's own checkout mechanism, not nested repos. Without an exclude entry, git would try to track the worktree's files as content of the parent repo. The plugin writes to `.git/info/exclude` (per-clone, not committed) so the host repo's tracked `.gitignore` stays untouched.

**Q: What's the typical workflow?**
`/empire-git:worktree-open <task>` → `code .claude/worktrees/<branch-dir>` → work & commit → `/empire-git:worktree-close --push` (or `/empire-git:worktree-merge` to fold into another branch first). Use `/empire-git:worktree-list` to see everything in flight.

**Q: How do port offsets work?**
Each worktree gets a deterministic 0–99 offset derived from its path. Same branch → same offset (bookmarkable). Different worktrees → near-zero collision odds. The script prints the offset on completion. If your app needs to read it, set `PORT_OFFSET` in the worktree's `.env` (manually or via your own post-setup hook) — the plugin no longer mutates `.env` automatically.

**Q: What happens to `.env` files?**
All `.env*` files are copied from the main repo into the worktree, preserving directory structure (monorepo-friendly). On `--reopen`, they're re-copied so worktrees pick up changes from the main repo. Symlinked `.env` files are skipped.

**Q: How does dependency install work?**
The script auto-detects the package manager from lockfiles in the worktree root: `pnpm-lock.yaml` → `pnpm install --frozen-lockfile`, `yarn.lock` → `yarn install --frozen-lockfile`, `bun.lockb`/`bun.lock` → `bun install --frozen-lockfile`, `package-lock.json` → `npm ci`, `uv.lock` → `uv sync`, `poetry.lock` → `poetry install`, `Pipfile.lock` → `pipenv install --deploy`, `Gemfile.lock` → `bundle install`, `Cargo.lock` → `cargo fetch`, `go.sum` → `go mod download`. No lockfile = skip.

**Q: When should I use `/empire-git:worktree-merge` instead of opening a PR?**
Two cases: **batching small fixes** (merge several tiny worktrees into one branch, open one PR), and **branch decomposition** (split a big feature into sub-worktrees, fold them back into the parent, then open one PR from the parent). For everything else, just `/empire-git:worktree-close --push` and PR normally.

**Q: Can I run multiple worktrees at once?**
Yes — that's the whole point. Each has isolated deps, ports, and env. Run `/empire-git:worktree-list` to see them all. A common pattern: one worktree for your main task, others for parallel Claude agents working on smaller things.

**Q: How do I update dependencies in a worktree?**
Run your normal install command inside the worktree directory (`pnpm install`, `bun install`, etc.). The worktree has its own `node_modules` — installs don't affect the main repo or other worktrees.

**Q: What if I forget about a worktree?**
`/empire-git:worktree-list --stale` shows worktrees with no recent activity. `/empire-git:worktree-cleanup` batch-removes stale ones (use `--dry-run` first to preview).

**Q: Is the main repo affected when I work in a worktree?**
No. The main repo's working directory, branch, and dev server are untouched. Only the shared `.git` directory is updated when you commit (which is the same as any branch switch).

**Q: How do I delete a branch and its worktree completely?**
`/empire-git:worktree-close <branch> --force` removes the worktree and deletes the local branch. Add `--push` first if you want to push before tearing down.

Versions

The database has no other skills named worktree-help.

Database snapshot: 13.11.2026 · package version bdece2bd2b05 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90worktrees:new
    Use when creating a new git worktree. Handles gitignore setup, worktree creation, and provides guidance. Invoke with "/worktrees:new <name>" or when user mentions "create worktree", "new worktree", "start feature in worktree", or "isolated workspace".
  • 90worktrees
    Use when creating, entering, checking, repairing or removing a git worktree, or when a worktree lacks dependencies, git hooks, skills or ignored files such as .env that the main checkout has.
  • 100setting-up-worktree-hooks
    Gives a repository one idempotent, repo-local worktree setup script (local env files, dependency install, build steps) that worktrunk's `.config/wt.toml` pre-start hook and Orca's `orca.yaml` scripts.setup both call, so every new git worktree is usable at once. Use when adding…
  • 95worktree
    Set up a new git worktree for parallel development. Creates the worktree, copies .env files, installs dependencies, and generates Prisma client. TRIGGER when user asks to set up a worktree, work on a branch in isolation, or needs a separate environment for a branch or PR.
  • 95worktrees-and-dev-servers
    Use when working with the repo's moonx root:wt worktree helper, Pierre-managed worktrees, dev-server port offsets, stale server cleanup, Playwright fixtures, or Chrome debug instances. Do not use this as a substitute for host-provided workspace isolation.
  • 100pro-init-worktree
    Create a git worktree from a branch name and copy only the needed local files (found via .gitignore) with reasons. Use for worktree creation, branch-isolated work, or /init-worktree.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.