Part 7: Git worktrees — parallel agents without context contamination

When you start using Claude Code seriously, you will eventually want to run two sessions at once. One agent refactoring authentication. Another adding a new API endpoint. Both working on the same repository.

The naive approach — two terminals, same directory — breaks almost immediately. Agent A edits auth.py. Agent B edits auth.py. One overwrites the other. The context is contaminated. Git becomes a mess.

Git worktrees solve this problem cleanly.

What a worktree is

A git worktree is a separate working directory linked to the same repository. You can have multiple worktrees from the same repo, each checked out to a different branch, each with its own filesystem state.

The repository itself — the .git folder, the commit history, the object store — is shared. The working directories are isolated.

# Create a worktree for a new feature branch
git worktree add ../myproject-feature feature/new-api

# Create a worktree from an existing branch
git worktree add ../myproject-auth feature/auth-refactor

# List all active worktrees
git worktree list

Each directory you create with git worktree add is a full checkout. You can run a separate Claude Code session in each one. The agents do not know about each other. They cannot overwrite each other's files.

Why this matters for parallel AI development

Claude Code works on the filesystem. When you give it a task, it reads files, modifies files, runs commands — all in the current working directory. If two sessions share a directory, they share state.

Worktrees eliminate that shared state. Each agent operates in isolation:

• Files modified in worktree A are not visible in worktree B until you merge
• Each worktree has its own branch — commits go to the right branch automatically
• If an agent goes in a bad direction, you discard the branch and remove the worktree — no cleanup needed in the main directory

The workflow becomes: branch → work → verify → merge → remove worktree. Each step is clean and reversible.

A practical example

Imagine you have two independent change requests ready:

1. CR-01: Refactor the database connection pooling
2. CR-02: Add a new analytics endpoint

These touch different parts of the codebase. Neither depends on the other. You can work on them in parallel.

# From your main repo directory
git worktree add ../myproject-cr01 feature/db-connection-refactor
git worktree add ../myproject-cr02 feature/analytics-endpoint

Now open two terminals. Start Claude Code in each worktree:

# Terminal 1
cd ../myproject-cr01
claude

# Terminal 2
cd ../myproject-cr02
claude

Give each agent its task. They run independently. You can check progress in each terminal. When one finishes, you review, verify, and merge — without waiting for the other.

When to use worktrees

Worktrees are the right tool when:

• Tasks are genuinely independent — they touch different files or systems
• Both tasks are ready to start now — no sequencing dependency
• The task is large enough to warrant isolation — a small change does not need a worktree; just queue it

Worktrees are overhead when:

• Task B depends on task A — run sequentially in the same session instead
• The task is trivial — creating a worktree takes longer than the change itself
• You are debugging — you want to reproduce, not isolate; use the main directory

A useful rule: if you would naturally describe two tasks as "I can work on these at the same time," use a worktree. If you would say "I need to finish this before I start that," do not.

Cleaning up

When a worktree's task is done and merged:

# Remove the worktree directory
git worktree remove ../myproject-cr01

# Prune stale worktree references (if you deleted the directory manually)
git worktree prune

# Optionally delete the branch (the history is preserved in main)
git branch -d feature/db-connection-refactor

The main repo directory is unaffected throughout. No cleanup there — that is the point.

Context isolation is the real benefit

The technical mechanism is git branches. The practical benefit is something else: each Claude Code session starts with a clean context for its task.

When an agent reads your project files in a worktree, it sees only the state relevant to that branch. It does not see work-in-progress from the other session. Its CLAUDE.md instructions still apply — they live in the repo and travel with the worktree — but its working context is bounded.

This is the same principle as giving a colleague a clear, scoped task and a quiet room to work in, rather than sitting them next to someone doing something different and asking them to ignore the noise.

Isolation is not just about preventing file conflicts. It is about giving each agent the best possible input.

Next in this series: Worktrees pair well with the change request workflow covered in Part 3. If you are using CLAUDE.md to encode task instructions, branch naming conventions, and changelog requirements, worktrees make those instructions more effective — each agent reads the same instructions, applies them to its own isolated branch.

See also: the T1K production methodology for how this approach scales to full client delivery.