The `using-git-worktrees` Claude Code Skill: Run Parallel Agents Without the Branch Chaos

What Is a Git Worktree?

A git worktree is a linked working directory that shares the same git repository but checks out a different branch. Instead of stashing changes, switching branches, and hoping nothing collides, you get multiple fully independent working trees from a single repo:

my-project/           ← main branch
my-project-feat-auth/ ← feature/auth branch (worktree)
my-project-fix-bug/   ← fix/payment-bug branch (worktree)

Each directory is its own isolated environment. Changes in one do not affect the others. You can run separate Claude Code sessions in each one simultaneously, and they will not interfere with each other.

What Is the `using-git-worktrees` Skill?

The using-git-worktrees skill teaches Claude to create, manage, and clean up git worktrees as part of its standard operating procedure. When the skill is loaded:

Claude creates a new worktree automatically before starting any significant task
Each worktree gets a descriptive branch name derived from the task
Claude works inside the worktree rather than directly on your main branch
When the task is complete, Claude presents a clean diff and waits for you to merge
Worktrees are cleaned up after merging

Without the skill, you would have to instruct Claude to do this manually every time. With it, the behavior is the default.

Installation

claude skill add using-git-worktrees

Or via the Skills panel: Customize > Skills > search “git-worktrees” > toggle on.

Prerequisites: git 2.5+ (worktrees were added in git 2.5; run git --version to check). Most systems running macOS or Linux with a recent git install are fine. No additional configuration is required.

Why This Matters for AI-Assisted Development

When you work with Claude Code on a long task, the risk of the agent touching files it should not touch — or partially completing work that conflicts with something else you are doing — is real. Worktrees solve this structurally rather than through careful prompting.

The key insight from the HN “separation of planning and execution” post is that the planning phase and the execution phase should be clearly separated. The using-git-worktrees skill enforces that separation at the filesystem level: Claude plans in context, creates a worktree to execute in, and hands back a clean branch when done. Your main branch never sees partial work.

This also unlocks parallel execution: you can run Claude Code in three separate worktrees simultaneously — one fixing a bug, one adding a feature, one updating documentation — and they compose cleanly through standard git merges.

What the Skill Actually Does

Automatic worktree creation — When you assign Claude a task that involves file modifications, the skill prompts Claude to create a worktree first:

git worktree add ../my-project-feat-auth -b feature/auth

Claude then cds into that directory and does all its work there.

Descriptive branch naming — Branch names are derived from the task description so you can track what each worktree is for at a glance.

Isolation by default — Claude does not touch your main branch, your uncommitted changes, or any other worktree. Each session has exactly one worktree.

Clean handoff — When work is complete, Claude produces a summary of changes, a git diff of the worktree against main, and instructions for merging or reviewing.

Cleanup instructions — After merging, Claude provides the commands to delete the worktree cleanly:

git worktree remove ../my-project-feat-auth
git branch -d feature/auth

Use Cases

Parallel feature development — Two or three Claude sessions working on separate features simultaneously, each in its own worktree. No stashing, no branch juggling, no surprises.

Safe experimentation — Ask Claude to try an approach you are not sure about. It works in an isolated worktree. If the result is not what you wanted, delete the worktree and try again. Your main branch is untouched.

Long-running refactors — Multi-file refactors that take many iterations can live in a dedicated worktree while you continue shipping from main. Merge when it is ready.

Review-before-merge workflows — Claude completes work in a worktree and stops. You review the diff on your own schedule and merge only what you approve.

Incident response — Need to ship a hotfix while a larger feature is in progress? The feature lives in its worktree; you create a hotfix worktree from main. Neither blocks the other.

The Planning/Execution Separation Pattern

The highest-engagement Claude Code workflow on HN right now combines this skill with a planning phase:

Plan in context — Give Claude the task, ask it to produce a plan. Do not let it write code yet.
Review the plan — Read it, adjust it, approve it.
Execute in a worktree — Claude creates the worktree, executes the approved plan, and stops when done.
Review the output — Inspect the diff before merging.

This loop gives you the speed of AI execution with meaningful human checkpoints. The using-git-worktrees skill makes step 3 automatic.

Tips and Gotchas

Name your worktrees semantically. The default branch names from the skill are reasonable, but task-specific names will help when managing several active worktrees.

Worktrees share the object store. Your repo history and all commits are shared — worktrees are not clones. This means they are fast to create and cheap on disk.

Do not nest worktrees. Keep worktrees as siblings of your main project directory, not inside it. This avoids accidental path collisions.

Check active worktrees anytime:

git worktree list