Git Worktrees for Parallel Development

If you’ve ever juggled multiple feature branches locally, you know the pain: stashing work, switching branches, reinstalling dependencies. Git worktrees solve this by letting you work on several features simultaneously in completely isolated directories. Here’s a scalable worktree workflow designed for parallel development—whether you’re working with AI coding agents or human developers.

The Problem

Traditional branch-based workflows create friction when working with AI code agents or in rapid development cycles:

• Stashing context: switching branches means stashing uncommitted changes and losing your working context
• Dependency thrashing: package.json changes between branches force you to reinstall node_modules repeatedly
• Coordination overhead: multiple agents or developers stepping on each other’s work without isolation

Worktrees eliminate this. Each feature gets its own directory tree, shared git history, and isolated environment.

The Setup

The architecture is simple but intentional:

Branch	Purpose
main	Production-ready code
staging	Integration and testing

All work happens in worktrees, never directly on branches in the main repository. The main repository stays clean and only tracks history.

The Worktree Script

A single bash script handles everything:

./bin/worktree create feature/my-feature

This single command:

• Validates the branch name (enforces feature/, fix/, chore/, etc. prefixes)
• Fetches the latest origin/staging
• Creates a git worktree in ../my-project-worktrees/feature-my-feature/
• Copies all .env files from the main repo
• Runs pnpm install —frozen-lockfile

The result: a fully isolated, production-ready development environment ready in about 10 seconds.

You can have your AI agent of choice create this script (like I did). I also recommend including a note in your agent context file that tells the agent to always create a new worktree when starting a new task. This makes worktree setup automatic.

Why Worktrees Work

Benefit	How It Works
Parallel Development	Work on multiple features in separate terminal tabs simultaneously
No Stashing	Each worktree has its own working directory. No context loss when switching.
Shared Git History	All worktrees share the same .git directory. Commits and branches stay visible everywhere.
Efficient Storage	Hard links in pnpm store use minimal extra disk space

The Workflow

Creating a new feature:

./bin/worktree create feature/new-thing

Enter the worktree:

cd ../my-project-worktrees/feature-new-thing

Code, commit, and push: Make changes, test locally, commit to your feature branch, push to origin

Open a PR: PR targets staging (enforced by GitHub Actions)

Review and merge: staging → test → main

Cleanup:

./bin/worktree remove feature/new-thing

Branch Policy (CI-Enforced)

GitHub Actions validates every PR to staging:

• feature/*, fix/*, bugfix/*, hotfix/*: feature and bug work
• chore/*, docs/*, refactor/*, test/*: maintenance work
• username/branch-name is rejected

This keeps the history clean and prevents accidental pushes to main.

Perfect for AI-Assisted Development

This setup shines with AI coding agents like Claude Code or GitHub Copilot (or any scenario with multiple parallel developers) because:

• Multiple agents or developers can work on different features without stepping on each other
• Each gets a clean, isolated environment with no context loss
• Humans and agents can collaborate safely by respecting feature isolation
• Every change is tracked and reviewable before merging

The automation removes the friction of environment setup, letting agents and developers focus on code rather than dependency management or context switching.

Wrapping Up

Git worktrees transform local development from a bottleneck into an asset. By combining worktrees with thoughtful branch naming and CI enforcement, you get a workflow that scales with multiple developers and agents. No more stashing, no more reinstalling dependencies, no more context loss.

If you’re using AI coding agents like Claude Code or GitHub Copilot, or working in rapid development cycles with multiple developers, this pattern is worth trying.