How to Use Git Worktrees with Superpowers for Isolated Development

Mar 18, 2026

The Problem

When I work on multiple features simultaneously, switching between branches becomes painful. I constantly stash changes, switch branches, and hope nothing breaks. This context switching kills my productivity.

I needed a way to work on multiple features in parallel without the overhead of switching branches.

Git worktrees solve this problem, but setting them up correctly requires careful directory management and safety checks. That’s where Superpowers’ using-git-worktrees skill helps.

What Are Git Worktrees?

Git worktrees let you check out multiple branches into separate directories from the same repository. Each worktree shares the same Git history but operates independently.

~/projects/myapp/           # main worktree (main branch)
~/projects/myapp/.worktrees/feature-auth/    # feature-auth branch
~/projects/myapp/.worktrees/fix-bug-123/     # fix-bug-123 branch

Instead of switching branches, I open a new terminal in the appropriate worktree directory. Each branch has its own isolated workspace.

Why Worktrees Matter for AI-Assisted Development

When I use AI coding assistants like Claude Code, worktrees become even more valuable:

Isolated AI context: Each worktree gets its own conversation history
Parallel AI sessions: I can run multiple AI tasks on different features
Clean separation: AI changes in one worktree don’t affect another
Easy rollback: Delete the worktree if the AI goes off track

Using the Superpowers Worktree Skill

The using-git-worktrees skill in Superpowers automates worktree creation with safety checks. It follows a systematic process to ensure reliable isolation.

Step 1: Directory Selection Priority

The skill first checks for existing worktree directories:

ls -d .worktrees 2>/dev/null     # Preferred (hidden)
ls -d worktrees 2>/dev/null      # Alternative

If neither exists, it checks your CLAUDE.md configuration:

grep -i "worktree.*director" CLAUDE.md 2>/dev/null

If no preference is found, it asks you:

No worktree directory found. Where should I create worktrees?

1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)

Step 2: Safety Verification

For project-local directories, the skill performs a critical safety check:

git check-ignore -q .worktrees 2>/dev/null

If the directory is NOT ignored, the skill takes action:

Adds the appropriate line to .gitignore
Commits the change
Proceeds with worktree creation

This prevents accidentally committing worktree contents to your repository—a common mistake that bloats repos and confuses teammates.

Step 3: Worktree Creation

Once safety is verified, the skill creates the worktree:

git worktree add .worktrees/my-feature -b my-feature

Or for an existing branch:

git worktree add .worktrees/existing-feature existing-feature

Practical Example: Parallel Feature Development

Let me walk through a real scenario. I’m working on a React application and need to implement two features simultaneously:

User authentication
Dashboard redesign

Without worktrees, I’d have to:

Stash authentication changes
Switch to dashboard branch
Work on dashboard
Switch back
Unstash changes
Hope for no conflicts

With Superpowers worktrees:

# In main repo directory
/using-git-worktrees

# Skill creates: .worktrees/feature-auth/
# Branch: feature-auth

Now I open two terminals:

cd .worktrees/feature-auth
# Start AI coding session for auth

# Stay in main directory
# Start AI coding session for dashboard

Both AI sessions run independently. No context switching. No stashing. No conflicts.

Integration with Superpowers Workflow

The using-git-worktrees skill fits into a larger development workflow:

graph LR
    A[Brainstorming] --> B[Design Approval]
    B --> C[using-git-worktrees]
    C --> D[writing-plans]
    D --> E[subagent-driven-development]
    E --> F[finishing-a-development-branch]

The skill activates after design approval, before plan execution. This ensures each feature gets its own isolated workspace from the start.

Best Practices

DO

Use hidden directories for project-local worktrees

# Preferred: hidden directory
.worktrees/

# Also acceptable: visible directory
worktrees/

Gitignore your worktree directory

# Worktrees
.worktrees/
worktrees/

Use descriptive branch names

# Good
git worktree add .worktrees/feature-user-auth -b feature/user-auth

# Bad
git worktree add .worktrees/temp -b temp

Clean up finished worktrees

git worktree remove .worktrees/feature-user-auth
git branch -d feature/user-auth

DON’T

Don’t commit worktree directories

# WRONG: Worktree contents in repo
git add .worktrees/
git commit -m "Added worktrees"

# CORRECT: Only commit the gitignore entry
echo ".worktrees/" >> .gitignore
git add .gitignore
git commit -m "Ignore worktree directory"

Don’t nest worktrees inside each other

# WRONG: Nested worktrees
.worktrees/
  └── feature-a/
      └── .worktrees/  # Don't do this

Don’t forget to prune old worktrees

# Check for stale worktrees
git worktree list

# Prune deleted worktree references
git worktree prune

Don’t use global directories for all projects

Global directories work for some workflows, but project-local worktrees are usually better because they:

Stay with the project when cloned
Are discoverable by teammates
Don’t require additional configuration

Common Issues

Issue 1: Worktree Already Exists

When I try to create a worktree that already exists:

fatal: 'feature-auth' already exists

I check existing worktrees:

git worktree list

Then remove the old one:

git worktree remove .worktrees/feature-auth

Issue 2: Branch Has Unmerged Changes

When I remove a worktree with unmerged changes:

fatal: cannot remove a worktree with uncommitted changes

I either commit the changes first:

cd .worktrees/feature-auth
git add .
git commit -m "WIP: save progress"

Or force remove if I want to discard:

git worktree remove --force .worktrees/feature-auth

Issue 3: Worktree Directory Not Ignored

If I see worktree files appearing in git status:

Untracked files:
  .worktrees/

I fix this immediately:

echo ".worktrees/" >> .gitignore
git add .gitignore
git commit -m "Ignore worktree directory"

The Superpowers skill handles this automatically, but it’s good to know the manual fix.

Workflow Comparison

Scenario	Without Worktrees	With Worktrees
Switch features	stash, checkout, unstash	cd to directory
Parallel AI sessions	Not possible	Multiple terminals
Isolated experiments	Create new clone	Create worktree
Disk space	Full clone per branch	Shared git objects
Context switching	Lost context	Preserved context

Summary

In this post, I showed how to use Superpowers’ using-git-worktrees skill for isolated development. The key points are:

Worktrees allow parallel branch development without context switching
The skill follows systematic directory selection with safety verification
Always gitignore worktree directories before creation
Integration with AI coding assistants provides isolated contexts
Clean up worktrees after merging to prevent clutter

The using-git-worktrees skill activates after design approval and before plan execution, ensuring each feature gets its own clean workspace. This transforms git branch management from a chore into a seamless part of the development workflow.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Git Worktrees Documentation
👨‍💻 Claude Skills Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!