Git worktrees: parallel development

Module: 9. Advanced features | Time: about 25 min reading + 30 min practice

The gist

Imagine you have two desks for the same project: at one you write the main code, at the other you experiment. They don't get in each other's way, and two agents can work at them at the same time. That's what Git worktrees are.

Terms in this lesson: git (a version control system), worktree (a parallel working copy of a repository), CI/CD (Continuous Integration / Continuous Delivery), GitHub Actions (GitHub's built-in automation system), workflow (a sequence of automated steps), agent (an AI that carries out tasks on its own).

Key concepts

Git and GitHub: local vs. cloud
Worktree = parallel working copies of one repository
Two agents on two branches = parallel development without conflicts
Built-in support in Claude Code: claude --worktree <name>
GitHub Actions and CI/CD automation (continuous integration and delivery)

Theory

Git vs. GitHub: what's the difference

🎨 Picture this: Git is your personal diary with a history of every edit. GitHub is the bank safe deposit box where a copy of the diary is kept. If the diary burns, the copy in the box survives.

Git is a program that lives on your computer. It tracks every change to your project files and lets you:

Go back to any earlier version
Work on several branches in parallel
See who changed what and when

GitHub is a cloud platform that stores Git repositories. On top of storage, it gives you:

A cloud backup (if your computer dies, the code survives)
Teamwork
Pull requests for code review
GitHub Actions for automation

In short: Git is your personal diary, GitHub is the safe deposit box that holds a copy.

Branches and pull requests

🎨 Picture this: a branch is like a rough draft in a separate notebook. Your main notes stay untouched while you try a new structure in the draft. If it works, you copy it into the main notes (merge). If not, the draft goes in the trash.

A branch is a parallel line of development. You create a branch to work on a feature without breaking the main code:

bash

git checkout -b feature/payment-integration
# All changes now go into the feature/payment-integration branch
# The main branch (main) stays untouched

A pull request (PR) is a proposal to merge the changes from a branch into the main one. For a solo developer it's useful as a record of decisions. For a team it's the required code review step.

What Git worktrees are

🎨 Picture this: a worktree is two desks for one project. At the first you write the main code, at the second you fix a bug. The filing cabinet is shared, but the desktops are separate, so nothing gets mixed up.

Normally you have one working copy of a repository. Worktrees let you have several working copies at once, each on its own branch.

Without worktrees:

Code

my-project/          ← one folder, one branch
  src/
  tests/

Want to switch to another branch? You have to run git stash or git checkout, and you lose your current context.

With worktrees:

Code

my-project/              ← main branch (main)
  src/
  tests/

my-project-feature-A/   ← feature-A branch
  src/
  tests/

my-project-hotfix/       ← hotfix branch
  src/
  tests/

Three separate folders, three different states of the code, one repository under the hood.

Why this matters with Claude Code

🎨 Picture this: two agents in two worktrees are like two surgeons in two operating rooms. One does a scheduled operation (the main feature), the other an emergency one (the hotfix). The same anesthesiologist serves both, and neither surgeon has to know about the other.

Each Claude Code instance works with the files in its own folder. Start Claude Code in my-project/ and it works with main. Start it in my-project-feature-A/ and it works with feature-A.

A parallel development scenario:

Code

Agent 1 (in my-project/):
→ Writes the main order-processing workflow
→ Integrates the database
→ Writes tests

Agent 2 (in my-project-feature-A/):
→ At the same time, builds the UI for viewing orders
→ Creates API endpoints
→ Writes documentation

Both work AT THE SAME TIME without getting in each other's way

Instead of "first one thing, then the other," you get parallel development. In practice this can noticeably shorten a project.

How to create and use worktrees

The shortest path: Claude Code's built-in flag. In current versions you don't have to create a worktree by hand:

bash

claude --worktree feature-auth

This command (short form -w) creates an isolated worktree in .claude/worktrees/feature-auth/ on a new branch called worktree-feature-auth and starts Claude in it right away. Run the same command with a different name in another terminal and you get a second isolated session. A few more useful things to know:

Add .claude/worktrees/ to .gitignore so the worktree folders don't show up in the main repository.
A worktree is a fresh copy: secret files like .env don't get copied into it. To have them copied automatically, put a .worktreeinclude file in the project root (same syntax as .gitignore).
You can simply ask Claude during a session: "work in a worktree." You can isolate a subagent too: add isolation: worktree to its file (see the Subagents lesson).
When you exit, Claude checks whether the worktree has unsaved work and asks whether to keep it or delete it.
You need a git repository. Documentation: code.claude.com/docs/en/worktrees.

Below is the same thing done by hand with git itself. It's worth knowing so you understand what's happening under the hood.

Step 1: Create a worktree

bash

# In the main project folder:
git worktree add ../my-project-feature-A feature-A

# What happens:
# - A my-project-feature-A folder is created next to the main one
# - It's switched to the feature-A branch
# - If the branch doesn't exist yet, add -b: git worktree add -b feature-A ../my-project-feature-A

Step 2: Start Claude Code in each folder

bash

# Terminal 1:
cd my-project
claude

# Terminal 2 (new window):
cd my-project-feature-A
claude

Step 3: See all active worktrees

bash

git worktree list
# Output:
# /path/to/my-project          abc1234 [main]
# /path/to/my-project-feature-A  def5678 [feature-A]

Step 4: Remove the worktree when you're done

bash

git worktree remove my-project-feature-A

GitHub Actions: CI/CD automation

🎨 Picture this: GitHub Actions is the quality control department at a factory. Every part (commit) gets checked automatically on the test bench (tests). If it fails inspection, it doesn't go to assembly (merge into main). And the QC inspector never sleeps.

CI/CD (Continuous Integration / Continuous Deployment) means tests and deployment run automatically whenever the code changes.

GitHub Actions lets you set this up without any extra services:

yaml

# .github/workflows/test.yml
name: Run Tests

on:
  push:
    branches: [main, feature-*]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      # action versions (@v4, @v5) get updated from time to time: check the action's page on GitHub
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: pytest

Now every time you push code, GitHub runs the tests automatically. If the tests fail, GitHub won't let the changes into main (once you turn on the matching branch protection rule).

What this means for Claude Code: the agent writes code and pushes it to a branch, GitHub Actions runs the tests, and you see the result right in the pull request, without opening a terminal.

Integration with Trigger.dev

If your project uses Trigger.dev for workflows, you can set up automatic deployment (checked against the Trigger.dev documentation in October 2026):

yaml

# .github/workflows/deploy.yml
name: Deploy to Trigger.dev

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy workflows
        run: npx trigger.dev@latest deploy
        env:
          TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}

Push to main → workflows deploy to Trigger.dev automatically. No manual deployment.

Practice

Task: run two agents in parallel using worktrees

Create a new repository or use an existing one:

bash

mkdir parallel-demo && cd parallel-demo
git init
echo "# Parallel Demo" > README.md
git add . && git commit -m "Initial commit"

Create a worktree for a second branch:

bash

git worktree add -b feature-backend ../parallel-demo-backend

Open two terminals:
- Terminal 1: cd parallel-demo && claude
- Terminal 2: cd parallel-demo-backend && claude
Give each agent a different task:
- Agent 1: "Create a README with a project description and installation instructions"
- Agent 2: "Create a basic Python script main.py with a hello_world function"
Watch both of them work at the same time

When they're done, merge the changes:

bash

cd parallel-demo
git merge feature-backend
git worktree remove ../parallel-demo-backend

Common mistakes

1. Forgetting to remove a worktree after merging Worktrees pile up folders on your disk. After merging a branch, always remove it:

bash

git worktree remove ../my-project-feature-A
# Check that nothing is left hanging around:
git worktree list

2. Trying to check out the same branch in two worktrees Git won't let you open the same branch in two worktrees at once. Each worktree = its own branch.

3. Editing worktree files from another editor If you've opened a worktree in Claude Code, don't edit the same files from VS Code at the same time. Conflicts are guaranteed.

4. Not creating the branch before the worktree If the branch doesn't exist yet, use the -b flag:

bash

git worktree add -b feature-new ../my-project-new

5. Merging without checking the tests Before merging from a worktree, run the tests on both branches. GitHub Actions automates this through CI.

Tools and resources

Git worktree: official documentation, git-scm.com/docs/git-worktree
GitHub Actions: CI/CD automation, docs.github.com/en/actions (free for public repositories; private ones get a monthly free allowance of minutes; check GitHub's pricing page for current limits)
Claude Code and worktrees: code.claude.com/docs/en/worktrees
GitHub CLI (gh): manage pull requests and Actions from the terminal, cli.github.com
Skill: superpowers:using-git-worktrees: an extended guide to worktree patterns

Key takeaways

A worktree isn't magic. It's just several folders on one repository. The power is that each agent works in its own isolated folder at the same time. GitHub Actions is your free QA department. Set it up once and the tests run on their own with every push. Parallel development with agents isn't the future. It's available right now with git worktree add.

Agent teams: worktrees + subagents = each agent works in its own worktree in parallel
Headless and CI/CD: GitHub Actions run the tests automatically on every push from any worktree

What's next

→ Headless and CI/CD: how to run Claude Code in automated scenarios with no human involved

Git worktrees: parallel development

The gist

Key concepts

Theory

Git vs. GitHub: what's the difference

Branches and pull requests

What Git worktrees are

Why this matters with Claude Code

How to create and use worktrees

GitHub Actions: CI/CD automation

Integration with Trigger.dev

Practice

Common mistakes

Tools and resources

Key takeaways

Related lessons

What's next