Git Worktrees in Claude Code: A Practical Guide to Parallel AI Agents

Most people using Claude Code run one session at a time. One terminal, one task, one branch. When they need to switch to something else, they stash their changes, swap branches, and lose their train of thought. Or they just wait until the first task finishes before starting the next one.

There is a better way. Git worktrees in Claude Code let you run multiple AI agents at the same time, each working on a completely separate task in a completely isolated copy of your codebase. One agent fixing a bug. Another building a feature. A third refactoring your tests. All running in parallel, none of them aware the others exist.

This week, Anthropic shipped built-in worktree support directly into the Claude Code CLI. A single flag. No manual git setup. No third-party tools. And it changes the way you work with AI coding agents. If you are not a developer and prefer the desktop app, Claude Cowork scheduled tasks offer a different kind of automation worth exploring.

This guide walks you through every step of setting it up. If you have never used git worktrees before, that is fine. I had not either until recently. By the end, you will know exactly how it works and why it matters.

What Are Git Worktrees (and Why Should You Care)?

Before touching Claude Code, you need to understand what a worktree actually is. The concept is simpler than it sounds.

Normally, a git repository has one working directory. That is the folder where your actual files live. When you switch branches with git checkout, git rewrites the files in that single directory to match the branch you are moving to. That is why you have to stash or commit changes before switching.

A git worktree is a second (or third, or fourth) working directory attached to the same repository. Each worktree can have a different branch checked out. They all share the same git history, the same remotes, the same commits. But each one has its own set of files on disk.

Think of it like having multiple copies of your project open in separate folders, except they are not copies. They are all connected to the same repository. A commit you make in one worktree is visible from every other worktree.

You can read the official git worktree documentation if you want the full technical reference. But for our purposes, all you need to know is this: worktrees give you isolated workspaces without duplicating your entire project.

Why This Matters for AI Coding Agents

Here is the problem worktrees solve. When you run Claude Code, it reads and writes files in your working directory. If you run two Claude Code sessions in the same directory at the same time, they will trip over each other. One agent edits a file. The other agent edits the same file. You get conflicts, broken code, and wasted time.

This is not a theoretical risk. Anyone who has tried running parallel Claude sessions in a single directory has hit this wall.

Worktrees fix it completely. Each Claude Code session gets its own directory with its own files and its own branch. The agents cannot interfere with each other because they are literally working in different folders.

This connects directly to how AI context windows work. Each Claude Code session maintains its own context, its own understanding of the codebase, its own memory of what it has done so far. Separate worktrees mean separate contexts. Clean, focused, and fast.

What You Need Before Starting

Let’s make sure you have everything in place. This will take two minutes.

Claude Code installed and authenticated. You need the CLI version, not just the web interface. If you can open your terminal, type claude, and get a response, you are good.

Git version 2.5 or later. Worktrees have been in git since 2015, so you almost certainly have this. Check with git --version in your terminal.

A git repository to work in. Navigate to any project you have under git version control. This will not work outside a git repo.

Claude Code version 2.1.49 or later. This is the version that added the built-in --worktree flag. Claude Code auto-updates, so you likely already have it. You can check by running claude --version.

That is it. No extra tools to install. No configuration files to create. The built-in flag handles everything.

Step 1: Open Your Project in the Terminal

Navigate to the root of your git project:

cd ~/projects/your-project

Make sure you are on your main branch with a clean working state. You do not strictly need a clean state, but it makes things simpler for your first time:

git status

If you see uncommitted changes, commit or stash them first:

git stash

Step 2: Start Claude Code in a Named Worktree

This is where the new built-in flag does its work. Instead of launching Claude Code normally, add the -w flag followed by a name:

claude -w feature-auth

That single command does several things at once. It creates a new directory at .claude/worktrees/feature-auth/ inside your project. It creates a new git branch called feature-auth. It checks out that branch in the new directory. And it starts a Claude Code session inside that directory.

You are now working in a fully isolated environment. Every file edit Claude makes happens in the worktree directory, not in your main project folder.

The name you pass after -w becomes both the directory name and the branch name. Pick something descriptive. If you are fixing a bug, call it bugfix-login. If you are adding a feature, call it feature-dashboard. You will thank yourself later when you have three or four of these running.

If you skip the name entirely, Claude generates a random one:

claude -w

This works, but named worktrees are easier to manage. Use names.

Step 3: Give Claude Its Task

Once the session starts, you are in a normal Claude Code conversation. The only difference is that it is running in an isolated worktree. Give it a task:

Add authentication middleware to the Express API using JWT tokens. Create the middleware, add it to the protected routes, and write tests.

Claude will start working. Leave it running.

Step 4: Open a Second Terminal and Start Another Agent

Open a new terminal window or tab. Navigate back to your project root:

cd ~/projects/your-project

Now start a second Claude Code session in its own worktree:

claude -w bugfix-pagination

Give this agent a completely different task:

The pagination on the /users endpoint returns duplicate results on page boundaries. Find and fix the off-by-one error.

Both agents are now running simultaneously. One is building authentication. The other is fixing pagination. They share the same repository history but cannot see or interfere with each other’s file changes.

Step 5: Check What Is Running

You can see all your active worktrees at any time. Open a third terminal (or use one where Claude is not running) and type:

git worktree list

You will see something like:

/home/you/projects/your-project         abc1234 [main]
/home/you/projects/your-project/.claude/worktrees/feature-auth    def5678 [feature-auth]
/home/you/projects/your-project/.claude/worktrees/bugfix-pagination  ghi9012 [bugfix-pagination]

Three entries. Your main working directory plus two worktrees, each on its own branch.

Step 6: Combine With tmux for a Better Workflow

If you are comfortable with tmux (a terminal multiplexer), you can launch Claude Code worktrees directly into tmux sessions with a single command:

claude -w feature-auth --tmux

This starts Claude in its own tmux session, letting you switch between agents using tmux key bindings (typically Ctrl-b then s to pick a session). Each agent gets its own terminal pane without cluttering your screen.

If you do not use tmux, separate terminal tabs work perfectly well. This is optional but worth exploring as you scale up.

Step 7: Clean Up When You Are Done

When you exit a Claude Code worktree session (type /quit or press Ctrl-C), Claude handles cleanup automatically.

If the agent made no changes, the worktree and its branch are removed straight away. No mess left behind.

If there are commits or uncommitted changes, Claude will ask you what to do. You can keep the worktree (preserving the branch and directory for later) or remove it (discarding everything).

To manually tidy up outside of Claude, you can run:

git worktree list
git worktree remove .claude/worktrees/feature-auth

One more thing. Add .claude/worktrees/ to your .gitignore file so the worktree contents do not show up as untracked files in your main repository:

echo ".claude/worktrees/" >> .gitignore

Do this once per project and forget about it.

Step 8: Merge Your Work Back

Each worktree creates a proper git branch. When an agent finishes its work and the code looks good, merge it back into your main branch the same way you would merge any branch:

git checkout main
git merge feature-auth

Or push the branch and open a pull request if that is your team’s workflow. The worktree is just a branch. All your normal git tools and processes apply.

When Parallel Agents Actually Help

Running three agents at once sounds impressive. But it is not always the right move. Here are the situations where it genuinely saves time.

Independent features on separate files. If one agent is working on the API and another on the frontend, they will not conflict. This is the sweet spot.

Long-running tasks you do not need to babysit. Start an agent on a refactoring job, open a second worktree, and continue your own work. When the first agent finishes, review what it did.

Trying multiple approaches to the same problem. Spin up two worktrees, give each agent the same task with a different approach, and compare the results. This is one of the most underrated patterns in AI-assisted development.

Where it does not help: tasks that depend on each other, or tasks that modify the same files. Keep your parallel work independent, and this approach will serve you well.

Subagents and Worktree Isolation

If you have been exploring Claude Skills or custom subagents, there is an extra layer to this. You can configure subagents to always run in their own worktree by adding isolation: worktree to the agent definition file. This means the subagent automatically gets an isolated workspace every time it runs, without you needing to pass the -w flag.

This is powerful for things like code review agents, test runners, or security auditors that should never touch your working files directly. The principle is the same as what we covered in context engineering: give AI the right context, in the right environment, and the results improve dramatically.

The Practical Takeaway

The full workflow from the Claude Code documentation on worktrees gives you additional options for manual worktree creation and management. But the built-in -w flag covers 90% of what most developers need.

The old way: one agent, one task, waiting for it to finish before starting the next thing. The new way: multiple agents, multiple tasks, each in its own isolated environment, all running at the same time.

Stop queuing your tasks. Start running them in parallel. Your codebase can handle it.