# using-git-worktrees

> A Claude Code skill that creates isolated git worktrees for feature work — handling directory selection, dependency installation, and gitignore safety so parallel branches don't pollute the main checkout.

**Use case**: Start isolated feature work without polluting the main checkout

**Canonical URL**: https://agentcookbooks.com/skills/using-git-worktrees/

**Topics**: claude-code, skills, git, planning

**Trigger phrases**: "set up a worktree", "isolate this feature", "work on this branch separately"

**Source**: [Jesse Vincent](https://github.com/obra/superpowers/tree/main/skills/using-git-worktrees)

**License**: MIT

---

## What it does

`using-git-worktrees` automates the setup of an isolated git worktree for a new branch — a fresh checkout in a separate directory that shares the same `.git` repo with the main checkout. The skill picks the worktree location using a priority order (existing convention → `CLAUDE.md` preference → user input), runs the right dependency install for the project type (Node, Rust, Python, Go are auto-detected), verifies the test baseline passes, and reports readiness.

The point is to make worktree-based development cheap. If creating an isolated branch checkout takes 10 minutes of manual setup, you don't do it; you work on top of dirty state and break things. If it takes 30 seconds, you use it for every non-trivial branch and stay clean.

## When to use it

- Starting a feature branch that will take more than one session
- Executing an implementation plan where you want fresh state
- Running an experiment you're not sure you'll keep
- Fixing a critical bug while a long-running feature branch is mid-flight
- Pairing with `dispatching-parallel-agents` — give each agent its own worktree

When *not* to reach for it:

- One-line fixes that don't need isolation
- Repos where worktree pollution has happened before (check `.gitignore` first)
- Projects without a clear dependency-install command (the skill assumes one exists)

## Install

From the [obra/superpowers](https://github.com/obra/superpowers) repo at `skills/using-git-worktrees/`. The skill assumes a CLAUDE.md may exist with worktree-location preferences; honors that before falling back to defaults.

## What a session looks like

1. **You ask for a worktree** for a named branch and feature.
2. **The skill resolves the location** — checks for an existing worktree directory convention, then a `CLAUDE.md` preference, then asks you.
3. **It creates the worktree** with `git worktree add`, branched from the right base.
4. **It detects the project type** and runs the install — `npm install`, `cargo build`, `pip install -e .`, `go mod download`. Skipped for projects where it isn't applicable.
5. **It verifies the baseline** — runs the test command if there is one, confirms a clean starting state, and reports anything that fails before you've even started work.
6. **It reports readiness** with the path and the baseline status.

The discipline that makes it work: the baseline gate. If the worktree's tests fail before you've made any changes, you find out immediately — not after spending an hour debugging your own broken commit.

## Receipts

_TODO — to be filled in from real worktree setup. Once the skill has spun up a worktree for a real feature branch, this section will capture: time-to-ready, how directory resolution behaved, whether dependency auto-detection picked the right tool, and any baseline failures the gate caught._

## Source and attribution

From [Jesse Vincent's superpowers repository](https://github.com/obra/superpowers/tree/main/skills/using-git-worktrees).

License: MIT.

The skill explicitly integrates with the rest of the superpowers methodology — it's the "set up isolation before executing a plan" step that pairs with `writing-plans`, `executing-plans`, and `finishing-a-development-branch`.