Let me teach you Git Worktrees in 5 min (if you crave that Parallel AI agent dopamine hit 😅)

Parallel Work Dilemma

In the era of AI agents doing parallel work, branches are not enough.

You have GitHub Copilot suggesting code. Claude generating entire features. AI agents running tests and fixing bugs. You want to try AI-generated refactors without breaking your stable code. All at once.

You need multiple things working in parallel. Different branches. Different Agents & Different dev servers.

Git worktrees solve this. They also keep your sanity if you're doing parallel work yourself (still not a believer in AI huh)

The Solution

Worktrees = multiple working directories for the same repo.

Same Git history. Different folders. Different branches. Work on them simultaneously.

No switching. No stashing. That's it.

5-Minute Practical Walkthrough

Setup: The Workspace Folder Pattern

Here's the structure we're aiming for:

Beautiful.Hark.Workspace/          ← Open THIS in your editor
├── Beautiful.Hark/                ← Main repo (main branch)
├── Beautiful.Hark.feature-auth/   ← Worktree (feature-auth branch)
└── Beautiful.Hark.hotfix/         ← Worktree (hotfix branch)

Important: Git worktrees work anywhere. But using a parent workspace folder saves you from insanity later. You can see all worktrees in your editor sidebar. Clean and organized.

For existing repos: Move them into a workspace folder. For new repos: clone into a workspace folder from day one.

Step 1: Create a Local Repo

Let's start fresh locally:

mkdir Beautiful.Hark.Workspace
cd Beautiful.Hark.Workspace
mkdir Beautiful.Hark
cd Beautiful.Hark
git init
echo "Hello World" > app.txt
git add .
git commit -m "initial commit"

Now open the workspace folder in your editor:

code ../

Your editor shows the Beautiful.Hark folder.

Step 2: Create Your First Worktree

Still inside Beautiful.Hark:

git worktree add ../Beautiful.Hark.feature-auth -b feature-auth

What happened?

Git created a new folder Beautiful.Hark.feature-auth next to your main repo. That folder has the feature-auth branch checked out. Your editor sidebar now shows both folders.

Worktrees are just copies of your repo with shared Git history. Edit one, commit. Edit the other, commit. No switching needed.

Step 3: See Both in Your Editor

Look at your editor sidebar:

Beautiful.Hark.Workspace/
├── Beautiful.Hark/                    ← main branch
│   └── app.txt
└── Beautiful.Hark.feature-auth/       ← feature-auth branch
    └── app.txt

Open app.txt from Beautiful.Hark. Edit it.

Open app.txt from Beautiful.Hark.feature-auth. Edit it differently.

Both files are open. Different branches. No switching. Watch the changes in real-time.

Step 4: Commit from Each Folder

Open two terminals.

Terminal 1:

cd Beautiful.Hark
echo "main work" >> app.txt
git add .
git commit -m "update main"

Terminal 2:

cd Beautiful.Hark.feature-auth
echo "feature work" >> app.txt
git add .
git commit -m "add feature"

Both commits exist. Different branches. Same repo.

Step 5: Real AI Agent Workflow

Create another worktree for AI experiments:

cd Beautiful.Hark
git worktree add ../Beautiful.Hark.ai-experiment -b ai-experiment

Now you have:

Terminal 1: Stable app running in Beautiful.Hark on port 3000

Terminal 2: AI agent making changes in Beautiful.Hark.ai-experiment on port 3001

Terminal 3: Your feature work in Beautiful.Hark.feature-auth

All happening simultaneously. Zero context switching.

Step 6: Cleanup

List worktrees:

git worktree list

Remove a worktree:

git worktree remove ../Beautiful.Hark.feature-auth

Never manually delete worktree folders. Always use git worktree remove.

When to Use Worktrees

Use worktrees:

AI agents working in parallel with your code. Multiple features in progress. Urgent hotfixes while feature work continues. PR reviews that need local testing. Running multiple dev servers on different branches.

Skip worktrees:

Tiny repos where switching is instant. You only work on one thing at a time. You're still learning basic Git.

Quick Reference

# Create worktree
git worktree add ../repo-name.branch-name -b branch-name

# List all worktrees
git worktree list

# Remove worktree
git worktree remove ../repo-name.branch-name

# Clean up stale references
git worktree prune

Branch vs Worktree

Important Notes

Merge conflicts can still happen if you merge branches with diverging changes. Worktrees don't prevent that. They just let you work on multiple branches without switching.

Workspace folders are optional but highly recommended. Git worktrees work anywhere. But organizing them in a parent folder keeps you sane.

Moving existing repos: Create a workspace folder. Move your repo into it. Continue working. That's it.

That's It

Worktrees are just multiple folders for the same repo.

Open the workspace folder in your editor. See all branches as folders. Work on them simultaneously.

In the era of AI coding agents, worktrees aren't optional. They're essential.

Next time you reach for git stash, create a worktree instead.