Skip to content
Skills Library
Programming · Building & coding

dev10x:git-worktree

/dev10x:git-worktree

Create git worktrees for clean workspace isolation. Offers two modes: native EnterWorktree (switches CWD in current session) or external worktree (IDE-isolated, requires restarting claude in new dir). TRIGGER when: starting feature work needing isolation, or executing implementation plans with independent tasks. DO NOT TRIGGER when: work can be done on the current branch without isolation, or user explicitly wants to stay in the current worktree.

Licence
MIT
Last repository change
12.10.2026

Assessment and security

90/ 100Class: good
Format15 / 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.
Content35 / 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
9
Scripts
7
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

What to check before installing
  • 7 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/create-worktree.sh, scripts/next-worktree-name.sh, scripts/session-end-cleanup.sh, scripts/setup-session-end-hook.sh, templates/post-checkout-node-husky.sh, templates/post-checkout-node.sh, templates/post-checkout-python-uv.sh

What it does and when to use it

Create git worktrees for clean workspace isolation. Offers two modes: native EnterWorktree (switches CWD in current session) or external worktree (IDE-isolated, requires restarting claude in new dir). TRIGGER when: starting feature work needing isolation, or executing implementation plans with independent tasks. DO NOT TRIGGER when: work can be done on the current branch without isolation, or user explicitly wants to stay in the current worktree.

Original author description

Create git worktrees for clean workspace isolation. Offers two modes: native EnterWorktree (switches CWD in current session) or external worktree (IDE-isolated, requires restarting claude in new dir). TRIGGER when: starting feature work needing isolation, or executing implementation plans with independent tasks. DO NOT TRIGGER when: work can be done on the current branch without isolation, or user explicitly wants to stay in the current worktree.

How it works

  1. Orchestration
  2. Workflow
  3. Path A — Same Session (EnterWorktree)
  4. Path B — External + New Session
  5. Hook Templates
  6. Cleanup
  7. Troubleshooting
Original SKILL.md headings · 337 lines, 1,603 words
SKILL.md preview
---
name: dev10x:git-worktree
description: >
  Create git worktrees for clean workspace isolation.
  Offers two modes: native EnterWorktree (switches CWD in current session)
  or external worktree (IDE-isolated, requires restarting claude in new dir).
  TRIGGER when: starting feature work needing isolation, or executing
  implementation plans with independent tasks.
  DO NOT TRIGGER when: work can be done on the current branch without
  isolation, or user explicitly wants to stay in the current worktree.
user-invocable: true
invocation-name: dev10x:git-worktree
allowed-tools:
  - mcp__plugin_dev10x_cli__next_worktree_name
  - Skill(dev10x:git)
  - mcp__plugin_dev10x_cli__create_worktree
  - Bash(${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/:*)
  - Bash(git worktree list:*)
  - Bash(git worktree remove:*)
---

# Git Worktree

## Orchestration

This skill follows `references/task-orchestration.md` patterns.
Create a task at invocation, mark completed when done:

**REQUIRED: Create a task at invocation.** Execute at startup:

1. `TaskCreate(subject="Create git worktree", activeForm="Creating worktree")`

Mark completed when done: `TaskUpdate(taskId, status="completed")`

**Announce:** "Using dev10x:git-worktree skill to create an isolated workspace."

## Workflow

### Step 1: Determine Branch Name

The branch name is needed by both paths. Follow project naming conventions:

- username: check `git branch -a` for the pattern used (e.g. `janusz`)
- slug: lowercase ticket title, hyphens, stop-words removed, max 3–4 words
- regular repo: `username/TICKET-ID/slug`
- worktree: `username/TICKET-ID/worktree-name/slug`
  (worktree name = basename of the worktree directory, e.g. `app-pos-7`)

### Step 2: Choose Worktree Mode

Present the two options with AskUserQuestion:

- **Same session** (Recommended) — native `EnterWorktree` tool switches CWD
  immediately; all subsequent git commands and skills (`commit`, `dev10x:gh-pr-create`,
  `branch:groom`) work without flags; worktree lives inside `.claude/worktrees/`
  (excluded from hook copies and `.gitignore`)
- **External + new session** — worktree created at `../.worktrees/<project>-NN`
  outside the project; IDE won't cross-index sibling worktrees; requires closing
  this session and opening a new one in the worktree directory

Continue to **Path A** or **Path B** based on the choice.

---

## Path A — Same Session (EnterWorktree)

### Step A1: Check post-checkout Hook

Read `.git/hooks/post-checkout` (or `.husky/post-checkout`) if it exists.
If it handles worktree setup adequately (uv sync, yarn install, env copy),
skip to Step A2.

If missing or incomplete, detect project type and propose the appropriate
template from the **Hook Templates** section below. Present to the user for
approval before writing. The hook must always ensure `.claude` exists —
either by copying from the source repo or creating an empty scaffold.

**Session config seeding (GH-705, ADR-0018).** Durable preferences
live in the global `~/.config/Dev10x/friction.yaml`, outside every
repo and therefore already shared by every worktree — nothing needs
copying into a new checkout. Templates instead **exclude** `Dev10x/`
from the `.claude/` copy, so no stale per-repo state (a legacy
`config.yaml`, an auto-advance doubt-sink) rides across, and then run
the seed to ensure the global `friction.yaml` and the self-ignoring
`.claude/Dev10x/.gitignore` exist:

```sh
# >>> Dev10x session-seed (ADR-0018) >>>
if command -v dev10x >/dev/null 2>&1; then
    dev10x session seed || true
elif command -v uvx >/dev/null 2>&1; then
    uvx dev10x session seed || true
fi
# <<< Dev10x session-seed (ADR-0018) <<<
```

The seed is idempotent — it leaves present files untouched — so it
needs no existence guard, and a missing `dev10x` CLI is non-fatal.
This block previously guarded on a per-repo
`.claude/Dev10x/session.yaml`; ADR-0018 retired that file, so nothing
creates it and the guard matched on every checkout (GH-1001). The
shipped `templates/post-checkout-python-uv.sh` is the reference
implementation.

**When the project already has an adequate post-checkout hook**, do NOT
overwrite it — **augment it idempotently**: read the hook, and only if
the `Dev10x session-seed` marker is absent, inject the block
above just before the hook's final cleanup/exit (inside the all-zeros
SHA guard if one exists). A hook that already contains the marker is
left untouched, so re-running this skill never duplicates the block.

### Step A1b: Detect Husky Version and Bootstrap ~/.huskyrc

When the project uses Husky, detect the version before creating
the worktree:

- **Husky v4**: `package.json` contains `"husky": { "hooks": ... }`
- **Husky v5+**: `.husky/_/husky.sh` exists

For **Husky v4** projects, worktrees lack `node_modules` until
`yarn install` completes, causing git hooks to fail. Check
`~/.huskyrc` and create it if missing:

```sh
# ~/.huskyrc — bootstrap for Husky v4 in worktrees
if [ ! -d "node_modules" ]; then
    echo "huskyrc: node_modules missing, skipping husky hook"
    exit 0
fi
```

For **Husky v5+** projects, no `~/.huskyrc` is needed.

**After writing any hook file**, always set executable permissions:
```sh
chmod +x .husky/post-checkout   # or .git/hooks/post-checkout
```

### Step A2: Create Worktree (native tool)

Call the native `EnterWorktree` tool:
- `name`: use the branch slug (e.g. `fix-railway-deployment`)

After `EnterWorktree` runs the session CWD is the new worktree. All
subsequent Bash calls, git commands, and skills operate inside it.

### Step A3: Continue Workflow

The session is now in the worktree. Resume the calling skill's next step
(ticket status, job story, summary). No restart needed.

**CWD & push discipline (GH-474 #6):** Although the session CWD is the
worktree, prefer **absolute paths** in Bash calls — a `cd X` in one call
does not persist to the next, so `cd subdir; <relative-path>` patterns
break when the CWD resets between calls. For pushing, raw `git push` is
hook-blocked on this worktree; use `Skill(dev10x:git)` (which wraps
`push_safe`) instead of `git push` directly.

---

## Path B — External + New Session

### Step B1: Determine Worktree Location

Default pattern: `../.worktrees/<project-basename>-NN`

Calculate the next available path:

```bash
${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/next-worktree-name.sh
```

Ask user to confirm (AskUserQuestion):
- **Create at `<calculated-path>`** (Recommended)
- **Custom location** — let user specify

### Step B2: Check post-checkout Hook

Same as Step A1 — read, verify, and propose a template if needed.
See **Hook Templates** section below.

### Step B3: Create the Worktree

```bash
${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/create-worktree.sh \
  <worktree-path> <branch-name> [base-ref] [repo-root]
```

- Omit `base-ref` to branch from the repo-root's current HEAD; pass it
  (e.g. `origin/develop`) to start the new branch from a specific ref.
- Omit `repo-root` when already inside the target repo.
- Pass `repo-root` when the CWD differs from the target repo.
- Both trailing args are positional — pass an empty string (`""`) to
  skip `base-ref` while still supplying `repo-root` (GH-960).

The `post-checkout` hook fires automatically after this script runs.

### Step B4: Install SessionEnd Cleanup Hook

```bash
${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/setup-session-end-hook.sh <worktree-path>
```

This writes a SessionEnd hook into `<worktree-path>/.claude/settings.local.json`
that prompts the user to remove the worktree when the new session ends.

### Step B5: Hand Off — STOP HERE

Claude Code sessions have a fixed CWD. `cd` inside a Bash call does not
persist, so every subsequent git command would need `git -C <path>` and
skills like `dev10x:gh-pr-create` (whose `verify-state.sh` runs plain `git`) would fail.

Print this message and **stop — do not continue with ticket workflow steps**:

```
✅ Worktree ready
   Path:   <worktree-path>
   Branch: <branch-name>

Close this session and open a new one in the worktree:

  cd <worktree-path> && claude

Copy the command above, close this session, then paste it in your terminal.
The new session will have the correct CWD and all skills will work normally.
```

---

## Hook Templates

Templates for projects that lack a `post-checkout` hook.

### All hooks: use the all-zeros SHA guard

`git worktree add` passes `0000000000000000000000000000000000000000` as `$1`
(previous HEAD) when creating a new worktree. Guard on this value — do NOT
use `[ -f .git ]` which fires on every branch checkout inside any worktree:

```sh
if [ "$1" = "0000000000000000000000000000000000000000" ]; then
    # new worktree — run setup
fi
```

### Detect project type

| Check | Template |
|---|---|
| `uv.lock` or `pyproject.toml` exists | Template A (Python/uv) |
| `package.json` + `.husky/` directory | Template B (Node + Husky) |
| `package.json` without Husky | Template C (Node, no Husky) |

A project can match multiple templates (e.g. Django + SvelteKit). Apply all.

### Hook file location

| Condition | Write to |
|---|---|
| Husky present (`prepare` script or `.husky/` dir) | `.husky/post-checkout` (tracked) |
| No Husky | `.git/hooks/post-checkout` (untracked, local only) |

Husky overwrites `.git/hooks/` on every `yarn/npm install`. Writing to
`.git/hooks/post-checkout` in a Husky project means changes are silently lost.

### Template A: Python/uv

Source: [`templates/post-checkout-python-uv.sh`](./templates/post-checkout-python-uv.sh)

Copies `.env`, `development.secrets.env`, `.claude/` (excluding WIP), `.idea/`,
and runs `uv sync`.

**After creating a Python/uv worktree**, run `dev10x:ide-normalize` to fix
stale PyCharm `.idea/` module-name references, disable
`ADD_CONTENT_ROOTS` / `ADD_SOURCE_ROOTS` flags (which conflict with editable
installs — see [PEP 660 / PYTHONPATH conflict](../ide-normalize/references/pep660-pythonpath-conflict.md)),
and detect the PyCharm uv-SDK `FLAVOR_DATA` gap that causes `ModuleNotFoundError`
on first launch.

### Template B: Node.js + Husky (write to `.husky/post-checkout`)

Source: [`templates/post-checkout-node-husky.sh`](./templates/post-checkout-node-husky.sh)

Copies `.env`, `.claude/` (excluding WIP), and runs `yarn install --frozen-lockfile`.

For monorepos (yarn workspaces), run `yarn install --frozen-lockfile` from
the repo root — this installs all workspace packages in one pass.

### Template C: Node.js without Husky (write to `.git/hooks/post-checkout`)

Source: [`templates/post-checkout-node.sh`](./templates/post-checkout-node.sh)

Copies `.env`, `.claude/` (excluding WIP), and runs `yarn install` or `npm ci`.

Make executable: `chmod +x .git/hooks/post-checkout`

**Never symlink `node_modules`** — a symlink means `yarn add/remove` in any
worktree mutates the shared directory. Always run `yarn install --frozen-lockfile`
(fast via Yarn's hardlink cache).

---

## Cleanup

The SessionEnd hook installed by Path B prompts:

> This session used worktree at `<path>`. Remove it? [y/N]

If yes: `git worktree remove <path>`
If no: the worktree persists for future sessions.

Manual removal:

```bash
git worktree remove <path>
git worktree remove --force <path>  # if dirty
git worktree list                   # list all worktrees
```

## Troubleshooting

### EnterWorktree Failure Recovery

If `EnterWorktree` fails (e.g., due to a hook error), it may leave
a partial worktree and orphan branch. Clean up manually:

```bash
git worktree remove <worktree-path> --force
git branch -D <worktree-branch>
```

Common failure causes:
- Husky v4 hooks require `node_modules` (see Step A1b)
- Yarn Berry needs `--immutable` not `--frozen-lockfile`
- Hook file not executable (ensure `chmod +x` after writing)

### PyCharm Crashes After Opening a New Worktree

**Symptom**: `uv run /full/path/.venv/bin/python manage.py …` crashes with
`ModuleNotFoundError: No module named 'collections.abc'`.

**Causes** (may be compounding):

1. **PyCharm uv-SDK FLAVOR_DATA gap** — PyCharm auto-creates an SDK entry
   with empty `FLAVOR_DATA="{}"`, missing `UV_VENV_PATH` / `UV_TOOL_PATH`.
   Result: PyCharm constructs the wrong launch command. Fix: run
   `dev10x:ide-normalize` (Step 5) or follow the manual recipe in
   [`../ide-normalize/references/pycharm-uv-sdk-gap.md`](../ide-normalize/references/pycharm-uv-sdk-gap.md).

2. **ADD_CONTENT_ROOTS / ADD_SOURCE_ROOTS injecting PYTHONPATH** — These
   run-config defaults activate `sitecustomize` bootstrappers (New Relic,
   DataDog APM, etc.) that crash under uv-managed Python. Fix: run
   `dev10x:ide-normalize` (Step 3) to set both flags to `false`.
   Background: [`../ide-normalize/references/pep660-pythonpath-conflict.md`](../ide-normalize/references/pep660-pythonpath-conflict.md).

**Quick fix**: `dev10x:ide-normalize` addresses both causes.
Files in this package (9)
  • SKILL.md 13 KB
  • evals/evals.json 8 KB
  • scripts/create-worktree.sh 1 KB
  • scripts/next-worktree-name.sh 1 KB
  • scripts/session-end-cleanup.sh 2 KB
  • scripts/setup-session-end-hook.sh 2 KB
  • templates/post-checkout-node-husky.sh 4 KB
  • templates/post-checkout-node.sh 4 KB
  • templates/post-checkout-python-uv.sh 6 KB

Versions

The database has no other skills named dev10x:git-worktree.

Database snapshot: 13.11.2026 · package version ea45defd7eaa (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

  • 95dev_manage_git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. Triggers: worktree, git worktree, isolated workspace, feature branch…
  • 84using_git_worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
  • 100using-git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
  • 100worktree
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
  • 100using-git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
  • 100using-git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback

Feedback and reports

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