Git worktrees: run multiple agents without file conflicts

If you're running more than one Claude Code agent at the same time, they're fighting over the same files. Every edit one agent makes is immediately visible to the other. That's not parallelism. That's chaos with extra steps.

Git worktrees fix this. They give each agent its own isolated file system, its own branch, and its own working directory. The agents share the same repository history but nothing else. This is the workflow that practitioners actually use when they run multiple agents in production.

---

What worktrees actually do

Git has always let you switch branches inside a single folder. The problem is that "switching" means only one branch is active at a time. Open two windows of your editor in the same repo and both windows point at whatever branch is currently checked out. Open a second Claude Code session in that same folder and both sessions read from, and write to, the same files.

A worktree creates a separate folder on your machine that is linked to the same repository but checked out to a different branch. The history and commits are shared. The working files are not.

The practical result: you can run agent one on a bug fix, agent two on a new feature, and they never touch each other's work. When they're done, you merge both branches independently.

---

How to create a worktree with Claude Code

You don't need to memorize Git syntax. Claude Code handles the command for you. Inside your Claude Code session, describe what you want.

You: Create a new git worktree based on main, name the branch dev-2

Claude will run the underlying git worktree add command, create a new folder adjacent to your current project, check out the new branch, and report back with the folder path.

# What Claude runs under the hood
git worktree add ../my-project-dev2 -b dev-2 main

That creates a folder called my-project-dev2 next to your existing project folder, checked out to a new branch called dev-2.

After Claude creates it, you open the new folder in a separate editor window. Now you have two independent workspaces: one on dev, one on dev-2. Each window can run its own Claude Code session.

> Approve worktree commands automatically. If you're regularly creating worktrees, add git worktree add to your auto-approved commands in Claude Code settings. It saves a confirmation click every time.

---

Setting up the two-window workflow

Once your worktree exists, the two-window setup takes about thirty seconds.

1. Window left: Your original project folder, checked out to dev or main. 2. Window right: The worktree folder (my-project-dev2), checked out to dev-2.

Both windows show Claude Code running. Both are pointing at the same repository. Neither can see the other's file changes.

Verify you're on separate branches by checking the branch indicator in the bottom-left of each editor window. Left shows dev. Right shows dev-2. If both show the same branch, the worktree isn't open yet.

Left window:   /my-project         [dev]
Right window:  /my-project-dev2    [dev-2]

Claude Code has a security boundary. It can't run commands that require navigating outside its working folder. When you first create the worktree, Claude may give you the terminal command to open the new folder rather than opening it itself. Copy it, run it in a new terminal tab. That's the one manual step in an otherwise automated setup.

---

When to reach for this workflow

Not every task needs worktrees. A single-agent session handles most client work fine. Worktrees add overhead. Use them when the payoff is real.

Use worktrees when:

• Two or more agents need to edit the same types of files simultaneously. A landing page rewrite and a data export fix might both touch app.js. Without worktrees, they collide.
• Your engagement has multiple parallel workstreams that need to stay isolated until review. Client A's reporting module and Client B's onboarding flow shouldn't share a branch.
• Each issue or feature gets its own branch. If that's your standard practice, worktrees are the only way to work on multiple issues at once without constant branch switching.
• You're testing a significant change but need the main branch available for urgent fixes. The worktree holds the experiment while the original folder handles production patches.

Skip worktrees when:

• You're running one agent on one task. A single session is faster to set up and easier to manage.
• The tasks touch completely different parts of the codebase with no file overlap. In that case, sequential sessions may be simpler.
• You're early in a client engagement and still orienting. Get the lay of the land first.

---

Build a reusable worktree command

The same four or five words describe every worktree you'll ever create: new branch, based on main, open in a new window. That's a strong candidate for a Claude Code custom command.

Inside Claude Code, you can create a slash command called /new-worktree that captures your exact preferences:

/new-worktree

Prompts for:
  - Branch name
  - Base branch (defaults to main)
  - Whether to open in a new window

Runs:
  git worktree add ../{branch-name} -b {branch-name} {base-branch}
  Lists all active worktrees for confirmation

The first time you set this up, it takes a few minutes. After that, spinning up a new isolated workspace is a single command. That speed compounds fast when you're managing three or four client engagements with parallel work in flight.

> Claude Code documents worktrees. The official Claude Code docs include a section on Git worktree support. If you want to go further than what's covered here, that's the right place to look. The AI models have a solid understanding of worktree commands because they're built on standard Git. Anything you'd do manually, you can ask Claude to do.

---

The production pattern

Practitioners running multi-agent workflows on real client engagements follow a consistent structure. Each issue or feature gets a branch. Each branch lives in its own worktree. Each worktree runs its own Claude Code session.

Repository: client-portal/

Worktrees:
  client-portal/           → branch: main       (stable, no active agents)
  client-portal-feat-auth/ → branch: feat-auth  → Agent 1: auth module
  client-portal-fix-csv/   → branch: fix-csv    → Agent 2: CSV export fix

When each agent finishes, you open a pull request from that branch. Review and merge them independently. No merge conflicts caused by agents working on the same files at the same time. Clean history. Traceable changes.

This is the architecture that makes multi-agent work actually manageable rather than a coordination problem you spend half your time debugging.