# Should your coding agent work in a separate git worktree?

Canonical URL: https://bestskillsforclaude.com/en/skills/using-git-worktrees
Language: en
Skill: using-git-worktrees
Publisher: Jesse Vincent (obra) (https://github.com/obra)
Source: https://github.com/obra/superpowers/tree/main/skills/using-git-worktrees
License as stated by the publisher: MIT
Runtime: Claude Code and other supported coding agents
Category: Build and ship
Last reviewed: 2026-10-27

For feature work, usually yes. Most of this skill is about not creating one you already have.

## Short answer
The using-git-worktrees skill in Jesse Vincent's superpowers makes sure feature work happens in an isolated workspace before implementation starts. It first detects whether the agent is already inside a linked worktree, asks before creating one, prefers the harness's native worktree tool over a manual git worktree add, then installs dependencies and runs the tests so the work starts from a known baseline. Use it whenever an agent writes code next to a checkout you care about.

Best for: Feature branches, plan execution and any session where an agent could leave half finished changes in your main checkout.
Skip it if: Your harness already gives every session its own worktree, or the change is a one line fix you would make on the current branch anyway.

## What to remember
- It loads at the start of feature work that needs isolation, or before a plan is executed, and says so when it does.
- Detection comes before creation. It compares git-dir with git-common-dir, guards against submodules, and never creates a second worktree inside the one it is already in.
- A native tool, which the skill describes with names like EnterWorktree or a --worktree flag, wins over git worktree add, which would leave state the harness cannot see.
- A failing baseline is reported rather than ignored, so later failures are not confused with ones that were already there.

## What it changes in practice
An agent that edits your main checkout leaves you two bad options when it goes wrong: untangle its changes from yours, or throw both away. A worktree gives the agent its own directory and branch on the same repository, so a failed attempt costs you a deleted folder.
Most of the skill exists to avoid duplicate isolation. Some harnesses already run each agent in a worktree they manage, and an agent that runs git worktree add on top of that produces what the skill calls phantom state, a workspace the harness can neither see nor clean up. Step 0 checks first, Step 1 prefers the native tool, and git comes last.
- Directory: your stated preference, then an existing .worktrees or worktrees folder, then a new .worktrees at the project root.
- Setup: npm install, cargo build, pip install, poetry install or go mod download, chosen from the files present.
- Baseline: the project's test command, with failures reported before any work starts.

## Where it disappoints
Setup is a fixed lookup by file name. A pyproject.toml triggers poetry install, which is wrong for projects managed with a different tool, and a repository with several manifests at its root gets every matching command. Expect to correct it on unusual layouts.
In one case it also changes your repository on its own: if the worktree directory is not ignored, it adds it to .gitignore and commits. That is the safe default for the repository and still a commit you did not write, so add the entry yourself if you care about history.

## Install and first run
1. In Claude Code, install superpowers with /plugin install superpowers@claude-plugins-official. The collection is MIT licensed, and this skill is a single SKILL.md that needs git and your project's own toolchain.
2. If you expect the git fallback, add .worktrees/ to .gitignore yourself first. Otherwise the skill adds the entry and commits that change in your current checkout.
3. Read the baseline report before letting work continue. If the tests fail before any change, the skill stops and asks, and that is the moment to decide.

## Questions
### What is a git worktree?
A second working directory attached to the same repository and checked out on its own branch, so two lines of work do not share files on disk.

### Will it create a worktree without asking?
No. In a normal checkout it asks first unless your instructions already state a preference, and if you decline it works in place.

### Which superpowers skills depend on it?
executing-plans and subagent-driven-development both call it to create a workspace, or verify the existing one, before they start.

## Sources
- obra/superpowers on GitHub: https://github.com/obra/superpowers
- obra/superpowers, using-git-worktrees skill directory: https://github.com/obra/superpowers/tree/main/skills/using-git-worktrees
- obra/superpowers README, installation and workflow: https://github.com/obra/superpowers/blob/main/README.md
- obra/superpowers LICENSE (MIT): https://github.com/obra/superpowers/blob/main/LICENSE

## Other languages
- Spanish: https://bestskillsforclaude.com/es/skills/using-git-worktrees
- Brazilian Portuguese: https://bestskillsforclaude.com/pt-br/skills/using-git-worktrees
- Japanese: https://bestskillsforclaude.com/ja/skills/using-git-worktrees