English | 日本語

Running Claude Code in Parallel with Git Worktree

This repository is an experimental environment for running multiple Claude Code instances in parallel using git worktree.

Overview

With Git worktree, you can check out multiple branches from the same repository into different directories and run an independent Claude Code session in each one. This lets you work on multiple features or bug fixes at the same time.

Benefits

• Each worktree has its own independent file state
• Prevents interference between Claude instances
• Enables parallel development across different branches
• Shares the same Git history and remote connection

Setup

1. Create a new worktree

# Create a worktree along with a new branch
git worktree add worktrees/feature-a -b feature-a

# Create a worktree for an existing branch
git worktree add worktrees/bugfix-123 bugfix-123

2. Run Claude Code in each worktree

# Terminal 1
cd worktrees/feature-a
claude

# Terminal 2  
cd worktrees/bugfix-123
claude

Experimental Environment Layout

This repository is configured with the following worktrees:

• main - the main branch (root directory)
• worktrees/feature-a - for the feature-a branch
• worktrees/bugfix-123 - for the bugfix-123 branch

Usage Examples

1. Fix a bug while developing a feature

   • Develop a new feature in the feature-a worktree
   • At the same time, make an urgent bug fix in the bugfix-123 worktree

2. Validate different approaches

   • Try different implementation approaches across multiple worktrees
   • Pick the best solution and merge it

Notes

• Each worktree is independent, but they all share the same Git repository
• To remove a worktree, use git worktree remove <path>
• We recommend cleaning up worktrees you no longer use on a regular basis

Managing Worktrees

# List all worktrees
git worktree list

# Remove a worktree
git worktree remove worktrees/feature-a

# Clean up unused worktrees
git worktree prune

Helpful Scripts

This repository includes scripts that make worktree management easier:

# Create a new worktree and open it in Cursor
./scripts/create-worktree.sh user-auth feature

# Display the list of worktrees in a readable format
./scripts/list-worktrees.sh

Development

The helper scripts are linted and smoke-tested via a Makefile:

make help   # List available targets
make lint   # Lint shell scripts (shellcheck + bash syntax check)
make test   # Run the smoke test for the worktree scripts
make check  # Run lint and test together

make test runs the scripts inside a throwaway git repository and stubs the cursor command, so it never touches your real environment or opens an editor.

Related Documentation

• What Is Git Worktree? - The basic concepts of Git worktree
• Worktree Management in Cursor - How to manage worktrees efficiently in the Cursor editor
• Experiment Guide - Hands-on experiment instructions
• Worktree and gitignore - About gitignore settings for worktree directories

References

• Anthropic Claude Code Documentation
• Official Git Worktree Documentation