Claude Code Git Worktree Parallel Development Workflow

Managing multiple features, bug fixes, or experiments simultaneously without disrupting your main development environment becomes effortless when you combine Git worktrees with Claude Code. This approach lets you work across several branches in parallel, each with its own working directory, while Claude Code’s skill system helps orchestrate your workflow efficiently.

Understanding Git Worktrees

Git worktrees allow you to checkout multiple branches of the same repository simultaneously. Instead of stashing changes or maintaining separate clones, you create additional working directories that share the same Git history and objects. Each worktree operates independently, meaning you can have uncommitted changes in one while working on something entirely different in another.

The basic syntax for creating a worktree is straightforward:

git worktree add /path/to/worktree branch-name

This single command creates a new directory with its own working tree, connected to the same .git directory as your main repository. You can list all worktrees with git worktree list, and remove them with git worktree remove worktree-name.

Setting Up Your First Worktree

Imagine you’re developing a feature branch while simultaneously fixing a critical bug on another branch. Rather than context-switching manually, create separate worktrees for each task:

# Create worktree for your feature development
git worktree add ../myproject-feature feature-new-dashboard

# Create worktree for the bug fix
git worktree add ../myproject-bugfix hotfix-login-error

# List all worktrees to verify
git worktree list

Each directory now contains the exact state of its respective branch. You can open separate terminal windows, run different processes, or use tools like tmux to work across them without ever running git checkout.

Integrating Claude Code Skills

Claude Code’s skill system enhances this workflow significantly. When you load skills like frontend-design or pdf for specific tasks, having worktrees set up means you can direct Claude Code’s attention to the appropriate directory context immediately.

For instance, if you’re using the tdd skill to drive test-first development in your feature worktree, you simply specify the correct path when invoking Claude Code:

cd ../myproject-feature
claude --print "Load the tdd skill and help me write tests for the new dashboard component"

The supermemory skill becomes particularly valuable in parallel development workflows. It maintains context across your different worktree sessions, helping Claude Code understand which project state corresponds to which branch, even as you rapidly switch between contexts.

Practical Workflow Examples

Parallel Code Review and Development

When reviewing a pull request while developing your own feature, create a dedicated worktree for the review:

# Checkout the PR branch for review
git worktree add ../myproject-pr-review pr/123-feature-request

# Your active development stays untouched in the main directory
# Now review code in the dedicated worktree
cd ../myproject-pr-review

This approach keeps your development state clean. You can annotate code, run the review branch’s tests, and examine its behavior without affecting what you’re currently building.

Testing Multiple Environment Configurations

Worktrees excel when you need to verify behavior across different configuration states. Create worktrees representing different deployment environments or dependency versions:

git worktree add ../myproject-node18 feature-backend
git worktree add ../myproject-node20 feature-backend

Each worktree can have its own .nvmrc or environment configuration. Run your test suites in parallel to catch environment-specific issues before merging.

Experimenting with Refactoring

The skill-creator skill proves useful when developing custom Claude Code workflows for your worktree management. Before attempting a major refactor, create a worktree to experiment safely:

git worktree add ../myproject-refactor experimental/refactor-database-layer

If the refactor succeeds, merge it. If it doesn’t work out, abandon that worktree without any impact on your main development line.

Parallel Feature Development Strategy

When working on multiple features simultaneously, create separate worktrees branching from main. This lets Claude Code work on one feature while you manually work on another, with zero risk of mixing changes:

# Create worktrees for parallel development
git worktree add -b feature/user-auth ../project-auth main
git worktree add -b feature/payment-system ../project-payments main
git worktree add -b feature/notifications ../project-notifications main

Each worktree has its own independent working directory. You can run Claude Code in each directory to handle different aspects of your project concurrently.

Using a CLAUDE.md File for Worktree Context

Create a CLAUDE.md file in your main repository to define worktree-specific instructions that Claude Code will follow automatically when invoked from each directory:

# Worktree Guidelines

When working in feature worktrees:
- Focus on the specific feature for this branch
- Do not modify files outside the feature scope
- Run tests before marking a task complete

When working in hotfix worktrees:
- Prioritize minimal, targeted changes
- Include regression tests for the fix
- Verify fix works in main branch context

Automating Worktree Management

You can create shell aliases or scripts to streamline worktree operations:

# Add to your .bashrc or .zshrc
alias worktree-feature='git worktree add ../myproject-$(basename $PWD)-$1 $1'

# Usage
worktree-feature feature-payment-integration

For more sophisticated automation, consider a dedicated worktree-manager skill script:

#!/bin/bash
# Skill: worktree-manager

case "$1" in
  create)
    BRANCH_NAME="$2"
    WORKTREE_PATH="../project-${BRANCH_NAME}"
    git worktree add -b "$BRANCH_NAME" "$WORKTREE_PATH" main
    echo "Created worktree at $WORKTREE_PATH for branch $BRANCH_NAME"
    ;;
  list)
    git worktree list
    ;;
  cleanup)
    WORKTREE_PATH="$2"
    BRANCH=$(basename "$WORKTREE_PATH")
    git worktree remove "$WORKTREE_PATH"
    git branch -D "$BRANCH"
    echo "Removed worktree and branch $BRANCH"
    ;;
esac

You can also combine this with Claude Code’s MCP (Model Context Protocol) capabilities. Skills like internal-comms can automatically generate status updates about what you’re working on in each worktree, keeping your team informed without manual tracking.

Best Practices

Organize your worktree parent directory consistently. Many developers use a structure like ~/workspaces/project-name/ with subdirectories for each branch. This keeps related directories grouped and makes navigation intuitive.

Establish clear naming conventions using prefixes to identify worktree purpose at a glance:

Use prefixes like feat-, fix-, review-, exp- to identify worktree purpose
Include the ticket or issue number when applicable
Keep names lowercase with hyphens for consistency

Regularly prune stale worktrees to avoid accumulating directories for merged or abandoned branches:

git worktree prune

Worktrees share the .git directory, so they do not duplicate the entire repository. However, each worktree has its own working files. For large projects, be mindful of disk usage and remove worktrees when no longer needed.

Common Worktree Issues and Solutions

Issue: Detached HEAD in Worktree

When you create a worktree for a branch that does not exist yet, it starts in detached HEAD state. This is normal and expected. Once you make your first commit, the branch will be properly established.

Issue: Moving Files Between Worktrees

If you need to move files between worktrees, use standard file operations — Git handles the rest:

# Copy file from one worktree to another
cp ../project-feature/src/utils.js ../project-bugfix/src/utils.js

Issue: Permission Errors

Worktrees sometimes have permission issues on shared filesystems. Ensure consistent file permissions across all worktree directories.

Conclusion

Git worktrees combined with Claude Code create a powerful parallel development environment. You maintain multiple isolated working contexts without the overhead of separate repository clones, while Claude Code’s skill system—particularly when leveraging skills like xlsx for tracking or docx for documentation—amplifies your productivity across all branches simultaneously.

Whether you’re managing feature development alongside bug fixes, conducting code reviews, or experimenting with refactoring, this workflow scales from simple two-branch scenarios to complex multi-context projects. The key advantage is eliminating the mental overhead of state management: each worktree simply is its branch, requiring no careful stashing or complex git operations to preserve.

Built by theluckystrike — More at zovo.one