🔒 Supercharge Your AI Coding Workflow: A Complete Guide to Git Worktrees with Claude Code

In the age of AI assisted development, our workflows are evolving rapidly. Tools like Claude Code are transforming how we write, refactor, and debug code. But…

In the age of AI assisted development, our workflows are evolving rapidly. Tools like Claude Code are transforming how we write, refactor, and debug code. But with this power comes a new challenge: how do we safely let an AI agent make substantial changes to our codebase while maintaining control and continuing our own work? Enter Git worktrees, a powerful yet underutilized feature that pairs exceptionally well with AI coding assistants.

This guide will take you from worktree basics to advanced workflows specifically designed for AI assisted development. Whether you're a seasoned developer or just starting to integrate AI into your workflow, you'll find practical strategies to boost your productivity while maintaining code quality.

What Are Git Worktrees?

Git worktrees allow you to have multiple working directories attached to the same repository simultaneously. Think of them as parallel universes for your codebase, each checked out to a different branch, but all sharing the same Git history and object database.

Unlike cloning a repository multiple times (which duplicates everything), worktrees are lightweight. They share the .git directory with your main working copy, meaning:

No duplicate repository data eating up disk space

All worktrees stay synchronized with the same remote

Commits made in any worktree are immediately visible to all others

Branch operations in one worktree affect the shared repository

The Traditional Problem

Before worktrees, if you needed to work on multiple branches simultaneously, you had limited options:

Stash and switch: Constantly stashing your work, switching branches, then unstashing. This is error prone and disruptive.

Multiple clones: Cloning the repository multiple times. This wastes disk space and creates synchronization headaches.

Just deal with it: Finishing one task completely before starting another. This kills productivity when you're blocked or need to context switch.

The Worktree Solution

Worktrees eliminate these compromises. You can have your main branch checked out in one directory, your feature/authentication branch in another, and a bugfix/login-error branch in a third, all simultaneously accessible and all sharing the same repository.

my-project/                    # Main worktree (main branch)

my-project-feature-auth/       # Worktree for authentication feature

my-project-bugfix-login/       # Worktree for login bugfix

Each directory is a fully functional working copy. You can open them in separate IDE windows, run different dev servers, and switch between them instantly by simply changing directories.

Git Worktree Commands: The Complete Reference

Before diving into AI specific workflows, let's master the worktree commands you'll use daily.

Creating Worktrees

Create a worktree for an existing branch:

git worktree add ../my-project-feature ../path/to/worktree branch-name

Create a worktree with a new branch:

git worktree add -b new-branch-name ../path/to/worktree

Create a worktree based on a specific commit or tag:

git worktree add ../path/to/worktree commit-hash

git worktree add ../path/to/worktree v1.2.3

Create a detached HEAD worktree (useful for exploration):

git worktree add --detach ../path/to/worktree HEAD

Listing Worktrees

View all worktrees:

git worktree list

This outputs something like:

/home/user/projects/my-app           abc1234 [main]

/home/user/projects/my-app-feature   def5678 [feature/new-ui]

/home/user/projects/my-app-bugfix    ghi9012 [bugfix/login]

Get detailed information:

git worktree list --porcelain

Removing Worktrees

Remove a worktree (the safe way):

git worktree remove ../path/to/worktree

Force remove (if there are uncommitted changes):

git worktree remove --force ../path/to/worktree

Clean up stale worktree references:

If you manually delete a worktree directory, Git still tracks it. Clean up with:

git worktree prune

Moving and Repairing Worktrees

Move a worktree to a new location:

git worktree move ../old/path ../new/path

Repair worktree references after moving the main repository:

git worktree repair

Locking Worktrees

Prevent a worktree from being pruned (useful for worktrees on removable drives):

git worktree lock ../path/to/worktree

git worktree lock --reason "On external backup drive" ../path/to/worktree

git worktree unlock ../path/to/worktree

Why Worktrees Are Perfect for AI Assisted Development

Now let's explore why worktrees and AI coding assistants are a match made in developer heaven.

The AI Agent Challenge

When you're using an AI coding tool like Claude Code, you're essentially giving an intelligent agent access to modify your files. This creates unique challenges:

Concurrent work: While the AI is refactoring your authentication module, you might want to continue working on the UI. Without worktrees, you're blocked.

Experimentation safety: AI suggestions might be brilliant or they might break everything. You need a safe space to evaluate them.

Context preservation: If the AI's changes don't work out, reverting shouldn't disrupt your other work.

Multiple AI tasks: You might want to run multiple AI assisted tasks in parallel, each exploring different approaches.

The Worktree Advantage

Worktrees solve all these problems elegantly:

Isolation: AI changes happen in a separate directory. Your main work is untouched.

Parallelism: Run multiple AI tasks simultaneously in different worktrees.

Easy comparison: Diff between worktrees to evaluate AI suggestions against your original code.

Zero risk experimentation: Delete a worktree and its branch if the AI's approach doesn't pan out.

Continuous productivity: Keep working in your main worktree while AI processes in another.

Setting Up a Worktree Based AI Workflow

Let's build a practical workflow from the ground up.

Project Structure

I recommend organizing your worktrees in a consistent pattern. Here's a structure that works well:

~/projects/

├── my-app/                      # Main worktree (main/develop branch)

├── my-app-ai-refactor/          # AI working on refactoring task

├── my-app-ai-feature/           # AI implementing new feature

└── my-app-ai-experiment/        # AI exploring experimental approach

Why Use Helper Scripts?

While you can create and remove worktrees manually with Git commands, helper scripts provide several important benefits when working with AI assistants:

Consistency: When you're creating multiple worktrees throughout the day for different AI tasks, it's easy to make typos or forget your naming convention. Scripts enforce a consistent pattern every time.

Reduced cognitive load: Instead of remembering the exact syntax for worktree commands, branch naming patterns, and directory paths, you just run one command with a task name.

Error prevention: The scripts include validation to prevent common mistakes like forgetting to specify a task name or accidentally deleting the wrong worktree.

Onboarding: If you work on a team, scripts make it easy for everyone to follow the same workflow without memorizing commands.

Documentation: The scripts themselves serve as documentation for your workflow. New team members can read them to understand the process.

Where to Save Your Scripts

You have several options for where to store these scripts:

Option 1: In your project repository (recommended for team workflows)

my-project/

├── scripts/

│   ├── create-ai-worktree.sh

│   └── cleanup-ai-worktree.sh

├── src/

└── ...

Option 2: In your home directory (recommended for personal use across projects)

~/bin/

├── create-ai-worktree.sh

└── cleanup-ai-worktree.sh

If using ~/bin/, make sure it's in your PATH by adding this to your .bashrc or .zshrc:

export PATH="$HOME/bin:$PATH"

Option 3: As Git aliases (covered later in the Advanced section)

The Creation Script

This script automates the creation of a new worktree specifically for AI assisted tasks:

#!/bin/bash

# create-ai-worktree.sh

#

# Purpose: Creates a new Git worktree with a standardized naming convention

#          for AI assisted development tasks.

#

# Usage: ./create-ai-worktree.sh <task-name>

# Example: ./create-ai-worktree.sh refactor-auth



# Get the project name from the Git repository root directory name

PROJECT_NAME=$(basename $(git rev-parse --show-toplevel))



# Get the task name from the first argument

TASK_NAME=$1



# Build standardized names for the branch and worktree directory

BRANCH_NAME="ai/${TASK_NAME}"

WORKTREE_PATH="../${PROJECT_NAME}-ai-${TASK_NAME}"



# Validate that a task name was provided

if [ -z "$TASK_NAME" ]; then

    echo "Usage: create-ai-worktree.sh <task-name>"

    echo ""

    echo "Examples:"

    echo "  create-ai-worktree.sh payment-integration"

    echo "  create-ai-worktree.sh refactor-auth"

    echo "  create-ai-worktree.sh bug-fix-login"

    exit 1

fi



# Check if the branch already exists

if git show-ref --verify --quiet "refs/heads/${BRANCH_NAME}"; then

    echo "Error: Branch '${BRANCH_NAME}' already exists."

    echo "Either delete it first or choose a different task name."

    exit 1

fi



# Create the new branch and worktree simultaneously

git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH"



# Provide helpful output

echo ""

echo "=========================================="

echo "AI Worktree Created Successfully!"

echo "=========================================="

echo ""

echo "Worktree location: $WORKTREE_PATH"

echo "Branch name:       $BRANCH_NAME"

echo ""

echo "Next steps:"

echo "  1. cd $WORKTREE_PATH"

echo "  2. Install dependencies (composer install, npm install, etc.)"

echo "  3. Launch Claude Code: claude"

echo ""

echo "When finished:"

echo "  cleanup-ai-worktree.sh $TASK_NAME"

The Cleanup Script

This companion script safely removes a worktree and its associated branch when you're done:

#!/bin/bash

# cleanup-ai-worktree.sh

#

# Purpose: Safely removes an AI worktree and its associated branch.

#          Includes confirmation to prevent accidental deletion.

#

# Usage: ./cleanup-ai-worktree.sh <task-name>

# Example: ./cleanup-ai-worktree.sh refactor-auth



PROJECT_NAME=$(basename $(git rev-parse --show-toplevel))

TASK_NAME=$1

BRANCH_NAME="ai/${TASK_NAME}"

WORKTREE_PATH="../${PROJECT_NAME}-ai-${TASK_NAME}"



# Validate that a task name was provided

if [ -z "$TASK_NAME" ]; then

    echo "Usage: cleanup-ai-worktree.sh <task-name>"

    echo ""

    echo "Current AI worktrees:"

    git worktree list | grep "\-ai\-"

    exit 1

fi



# Check if the worktree exists

if [ ! -d "$WORKTREE_PATH" ]; then

    echo "Error: Worktree not found at $WORKTREE_PATH"

    echo ""

    echo "Current worktrees:"

    git worktree list

    exit 1

fi



# Show what will be deleted and ask for confirmation

echo "This will remove:"

echo "  Worktree: $WORKTREE_PATH"

echo "  Branch:   $BRANCH_NAME"

echo ""



# Check for uncommitted changes

cd "$WORKTREE_PATH"

if [ -n "$(git status --porcelain)" ]; then

    echo "WARNING: This worktree has uncommitted changes!"

    git status --short

    echo ""

fi

cd - > /dev/null



read -p "Are you sure you want to continue? (y/n) " -n 1 -r

echo ""



if [[ $REPLY =~ ^[Yy]$ ]]; then

    # Remove the worktree

    git worktree remove "$WORKTREE_PATH" --force



    # Remove the branch

    git branch -D "$BRANCH_NAME"



    echo ""

    echo "Successfully cleaned up: $TASK_NAME"

else

    echo "Cleanup cancelled."

fi

Installing and Using the Scripts

Follow these steps to set up the scripts on your system:

Step 1: Create the scripts

Create a bin directory in your home folder if it doesn't exist:

mkdir -p ~/bin

Create the creation script:

nano ~/bin/create-ai-worktree.sh

# Paste the script content, save and exit (Ctrl+X, Y, Enter)

Create the cleanup script:

nano ~/bin/cleanup-ai-worktree.sh

# Paste the script content, save and exit

Step 2: Make them executable

chmod +x ~/bin/create-ai-worktree.sh

chmod +x ~/bin/cleanup-ai-worktree.sh

Step 3: Add to your PATH (if not already done)

Add this line to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/bin:$PATH"

Then reload your shell configuration:

source ~/.bashrc  # or source ~/.zshrc

Step 4: Use them in any Git repository

# Navigate to any project

cd ~/projects/my-laravel-app



# Create an AI worktree for a payment feature

create-ai-worktree.sh payment-processing



# Output:

# ==========================================

# AI Worktree Created Successfully!

# ==========================================

#

# Worktree location: ../my-laravel-app-ai-payment-processing

# Branch name:       ai/payment-processing

# ...



# Navigate to the new worktree

cd ../my-laravel-app-ai-payment-processing



# Do your AI assisted work...



# When done, return to main project and clean up

cd ../my-laravel-app

cleanup-ai-worktree.sh payment-processing

Practical Example: Complete Workflow

Here's a real world example showing the scripts in action:

# You're working on your Laravel project

cd ~/projects/invoice-app

git status

# On branch main, everything clean



# You want Claude Code to implement a PDF export feature

create-ai-worktree.sh pdf-export



# Output shows the worktree was created at ../invoice-app-ai-pdf-export



# Move to the AI worktree

cd ../invoice-app-ai-pdf-export



# Install dependencies (worktrees don't share node_modules or vendor)

composer install

npm install



# Start Claude Code and give it the task

claude



# ... Claude Code implements the PDF export feature ...

# ... You review the changes, run tests, make adjustments ...



# Happy with the result? Commit and merge

git add .

git commit -m "feat: implement PDF export for invoices"



# Return to main project

cd ../invoice-app



# Merge the AI's work

git merge ai/pdf-export



# Clean up the worktree and branch

cleanup-ai-worktree.sh pdf-export



# Done! The PDF export feature is now in your main branch

This workflow keeps your main development environment clean, lets you experiment freely, and makes it trivial to discard failed experiments or merge successful ones.

Real World Workflow: AI Assisted Feature Development

Let's walk through a complete example of using worktrees with Claude Code to implement a new feature.

Scenario

You're building a Laravel application and need to implement a new payment processing feature. You want Claude Code to scaffold the initial implementation while you continue working on unrelated bug fixes.

Step 1: Create the AI Worktree

From your main project directory:

# Create a worktree for the AI to work in

git worktree add -b feature/payment-processing ../my-app-ai-payments



# Verify it was created

git worktree list

Step 2: Set Up the AI Environment

Navigate to the new worktree and ensure it's ready:

cd ../my-app-ai-payments



# Install dependencies (they're not shared between worktrees)

composer install

npm install



# Copy environment file if needed

cp .env.example .env

php artisan key:generate

Step 3: Launch Claude Code in the AI Worktree

Open Claude Code in the AI worktree directory:

claude

Now give Claude Code your task:

I need you to implement a payment processing system for this Laravel application. 



Requirements:

* Create a PaymentService class that integrates with Stripe

* Add a PaymentController with endpoints for creating and confirming payments

* Create the necessary migrations for storing payment records

* Add appropriate form requests for validation

* Write feature tests for the payment flow



Please implement this step by step, creating each component and explaining your decisions.

Step 4: Continue Your Own Work

While Claude Code works in the payment worktree, switch back to your main worktree:

cd ../my-app

Continue your bug fixes, completely unaffected by whatever Claude Code is doing in the other directory.

Step 5: Review AI Changes

Once Claude Code completes its task, review what it created:

# See what files were changed/created

cd ../my-app-ai-payments

git status



# Review the diff

git diff main



# Or compare specific files

diff ../my-app/app/Services/ ./app/Services/

Step 6: Test in Isolation

Run tests in the AI worktree to validate the implementation:

cd ../my-app-ai-payments

php artisan test --filter=Payment

Step 7: Merge or Iterate

If you're satisfied with the AI's work:

# Switch to main worktree

cd ../my-app



# Merge the AI's branch

git merge feature/payment-processing



# Clean up

git worktree remove ../my-app-ai-payments

git branch -d feature/payment-processing

If you need changes, either:

Return to the AI worktree and continue prompting Claude Code

Make manual adjustments in the AI worktree before merging

Discard and start fresh with a new approach

Advanced Workflow: Parallel AI Exploration

Sometimes you want the AI to explore multiple approaches simultaneously. Worktrees make this trivial.

The Multi Path Strategy

# Create three worktrees for different approaches

git worktree add -b ai/payments-stripe ../my-app-ai-stripe

git worktree add -b ai/payments-square ../my-app-ai-square

git worktree add -b ai/payments-braintree ../my-app-ai-braintree

Open Claude Code in each worktree with different prompts:

Stripe worktree: "Implement payment processing using Stripe's Payment Intents API..."

Square worktree: "Implement payment processing using Square's Web Payments SDK..."

Braintree worktree: "Implement payment processing using Braintree's Drop-in UI..."

Comparing Results

After all three implementations are complete:

# Compare code structure

diff -r ../my-app-ai-stripe/app/Services ../my-app-ai-square/app/Services



# Compare test coverage

cd ../my-app-ai-stripe && php artisan test --coverage

cd ../my-app-ai-square && php artisan test --coverage

cd ../my-app-ai-braintree && php artisan test --coverage

Selecting the Winner

Once you've evaluated all approaches:

# Merge your preferred implementation

cd ../my-app

git merge ai/payments-stripe



# Clean up all AI worktrees

git worktree remove ../my-app-ai-stripe

git worktree remove ../my-app-ai-square

git worktree remove ../my-app-ai-braintree



# Remove branches

git branch -D ai/payments-stripe ai/payments-square ai/payments-braintree

Best Practices for AI Worktree Workflows

Naming Conventions

Establish clear naming patterns:

Worktree directories: {project}-ai-{task} or {project}-{branch-type}-{description}

Branch names: ai/{task-name} or ai/{date}/{task-name}

This makes it easy to identify AI related work and clean up when done.

Commit Hygiene in AI Worktrees

Instruct your AI to commit frequently with meaningful messages:

As you implement this feature, please commit your changes at logical 

checkpoints with clear commit messages that explain what was done and why. 

Use conventional commit format (feat:, fix:, refactor:, etc.).

This gives you granular control when reviewing and the ability to cherry pick specific changes.

Regular Cleanup

AI experimentation can leave orphaned worktrees. Schedule regular cleanup:

# List all worktrees

git worktree list



# Prune any that were manually deleted

git worktree prune



# Remove stale AI branches

git branch --list 'ai/*' | xargs -n 1 git branch -d

Environment Variables and Secrets

Never let AI worktrees contain real credentials:

Use .env.example files with placeholder values

Create a specific .env.ai template for AI worktrees

Add AI worktree patterns to .gitignore if they might contain sensitive data

# .gitignore

.env

.env.ai

**/my-app-ai-*/.env

IDE Configuration

If you use VS Code, create a workspace file to manage multiple worktrees:

{

    "folders": [

        {

            "name": "Main Development",

            "path": "./my-app"

        },

        {

            "name": "AI: Payment Feature",

            "path": "./my-app-ai-payments"

        },

        {

            "name": "AI: Refactoring",

            "path": "./my-app-ai-refactor"

        }

    ],

    "settings": {

        "files.exclude": {

            "**/node_modules": true,

            "**/vendor": true

        }

    }

}

Troubleshooting Common Issues

"fatal: 'branch-name' is already checked out"

Git prevents the same branch from being checked out in multiple worktrees. Solutions:

# Create a new branch instead

git worktree add -b new-branch-name ../path



# Or detach HEAD in the blocking worktree first

cd ../blocking-worktree

git checkout --detach

Worktree Shows Outdated Code

If your AI worktree doesn't reflect recent commits from another worktree:

cd ../ai-worktree

git fetch origin

git rebase origin/main  # or merge, depending on your preference

Dependencies Not Working

Each worktree needs its own installed dependencies:

# Laravel

composer install

npm install



# SPFx

npm install



# ASP.NET Core

dotnet restore

Large Repository, Slow Worktree Creation

For very large repositories, worktree creation can be slow. Use sparse checkout:

git worktree add --no-checkout ../sparse-worktree branch-name

cd ../sparse-worktree

git sparse-checkout init --cone

git sparse-checkout set src/relevant-folder

Integrating with Your Development Workflow

Git Aliases for Common Operations

Add these to your .gitconfig:

[alias]

    # List worktrees with better formatting

    wt = worktree list



    # Create AI worktree quickly

    wt-ai = "!f() { git worktree add -b ai/$1 ../$(basename $(pwd))-ai-$1; }; f"



    # Remove AI worktree and branch

    wt-ai-rm = "!f() { git worktree remove ../$(basename $(pwd))-ai-$1 && git branch -D ai/$1; }; f"



    # Prune and clean

    wt-clean = "!git worktree prune && git branch --list 'ai/*' --merged | xargs -r git branch -d"

Usage:

git wt-ai payments      # Creates worktree and ai/payments branch

git wt-ai-rm payments   # Removes both

git wt-clean            # Prune stale worktrees and merged AI branches

Shell Functions for Complex Workflows

Add to your .bashrc or .zshrc:

# Start an AI assisted task

ai_task() {

    local task_name=$1

    local project_name=$(basename $(git rev-parse --show-toplevel))

    local worktree_path="../${project_name}-ai-${task_name}"



    git worktree add -b "ai/${task_name}" "$worktree_path"

    cd "$worktree_path"



    # Auto detect and install dependencies

    [ -f "composer.json" ] && composer install

    [ -f "package.json" ] && npm install

    [ -f "*.csproj" ] && dotnet restore



    echo "Ready! Opening Claude Code..."

    claude

}



# Quick cleanup

ai_cleanup() {

    local task_name=$1

    local project_name=$(basename $(git rev-parse --show-toplevel 2>/dev/null || echo $(basename $(pwd)) | sed 's/-ai-.*//'))

    local worktree_path="../${project_name}-ai-${task_name}"



    git worktree remove "$worktree_path" 2>/dev/null

    git branch -D "ai/${task_name}" 2>/dev/null

    echo "Cleaned up ai/${task_name}"

}

Conclusion

Git worktrees transform how we can work with AI coding assistants. By providing isolated, parallel working environments, they enable us to:

Let AI agents work autonomously without blocking our own progress

Experiment with multiple AI generated solutions simultaneously

Maintain clean separation between human and AI contributions

Safely evaluate and iterate on AI suggestions before merging

The investment in learning worktrees pays dividends every time you use an AI coding tool. The commands become second nature quickly, and the workflow improvements are substantial.

As AI assisted development continues to evolve, workflows like these will become increasingly important. The developers who master the tooling around AI integration will be the ones who extract the most value from these powerful assistants.

Start small: next time you have a task suitable for Claude Code, create a dedicated worktree. Experience the freedom of parallel development firsthand. Once you do, you'll wonder how you ever worked without it.

Have questions or want to share your own AI plus worktree workflows? Drop a comment below or reach out on social media. Happy coding!

Supercharge Your AI Coding Workflow: A Complete Guide to Git Worktrees with Claude Code