Introduction to Git Worktrees in Claude Code

Claude Code now supports Git worktrees directly in the CLI, and this changes how developers can work.

In real life, developers rarely work on just one thing at a time. One minute you are building a new feature. The next, you are fixing a bug. Then you are testing an idea you are not even sure will ship.

Traditionally, handling all of this in one repository can get messy. You switch branches. You stash changes. You try not to forget what you were doing five minutes ago. Sometimes you run into conflicts that slow everything down. It works, but it drains your focus and energy.

This is where worktrees help.

In this article, we will walk through how Claude Code uses Git worktrees to let you run multiple AI agents at the same time, each working in its own isolated environment. First, we will explain what Git worktrees are and why they matter. Then we will look at a practical example where Claude builds multiple features in parallel. Finally, we will explore a few advanced tips to help you get even more out of this workflow.

By the end, you will see how this approach helps you move faster while reducing mental overhead and avoiding unnecessary interruptions

The challenge of sequential development: why we need a better workflow

Before exploring the solution, understanding the problem is essential. The conventional approach to managing multiple tasks in a Git repository often leads to significant inefficiencies and risks that can hamper a project's velocity and quality.

The monolithic pull request problem

A common anti-pattern is to bundle multiple unrelated changes (say, a new feature, a bug fix, and a small refactor) into a single branch and, consequently, a single, massive pull request (PR). While it might seem efficient from the developer's perspective initially, this approach creates several downstream problems:

Difficult code reviews: Large PRs are notoriously difficult and time-consuming for team members to review. The cognitive load required to understand dozens of files and hundreds of lines of changes at once increases the likelihood that subtle bugs will be missed.

Delayed deployment: If a single part of the monolithic PR has an issue or requires further changes, the entire set of features is blocked from being merged and deployed. A perfectly good and complete feature could be held hostage by a buggy or incomplete one.

Increased merge conflicts: The longer a feature branch lives, the more it diverges from the main branch. This dramatically increases the probability of complex and difficult-to-resolve merge conflicts.

The pain of manual context switching

The alternative to monolithic PRs is to work on features in separate branches. However, in a single working directory, this involves constant context switching. Imagine you're working on feature-A and your manager asks you to immediately fix a critical bug. Your workflow might look like this: git stash your incomplete work on feature-A, git checkout main and git pull to get the latest code, git checkout -b hotfix-123 to create a new branch for the fix, fix the bug and create a PR, wait for the PR to be merged, git checkout feature-A, and git stash pop to reapply your changes, potentially dealing with conflicts if the hotfix touched the same files.

This process is disruptive. It breaks your flow state, and the stash command, while useful, can become a messy, hard-to-manage list of uncommitted changes. This is precisely the "mental load" that Claude Code's worktree integration aims to eliminate.

Understanding the magic: what is a Git worktree?

Git worktrees are not a new concept invented by Claude; they are a powerful, and perhaps underutilized, feature of Git itself. A worktree allows you to have multiple working directories (the files you see and edit) linked to a single Git repository. Each worktree can be checked out to a different branch, allowing you to work on multiple branches simultaneously.

Beyond a single directory

Think of your standard .git folder as the central database for your project's history. Usually, you only have one set of files (your working directory) that interacts with this database. With worktrees, you can create multiple, parallel working directories.

For example, you could have /path/to/my-project/ (your main directory, checked out to the main branch), /path/to/my-project-feature-A/ (a worktree, checked out to the feature-A branch), and /path/to/my-project-hotfix/ (another worktree, checked out to the hotfix-123 branch).

All three directories share the same .git history, but their files reflect the state of their respective branches. You can edit code in the feature-A worktree, cd into the hotfix worktree to make a change there, and run npm install in one without affecting the others. There's no need to stash or switch branches in a disruptive way.

Claude Code takes this powerful Git feature and automates it, making parallel development with AI agents seamless and intuitive.

Getting started with worktrees in Claude Code

Understanding the "why" sets the foundation for exploring the "how." A simple React "todos" application serves as the playground to demonstrate the power of Claude Code's worktree feature.

Prerequisites

Before beginning, ensure you have the following set up: Claude Code CLI (you must have the latest version installed), Git repository (your project must be a Git repository; if starting from scratch, run git init in your project's root directory), and initial commit (your repository must have at least one commit; Git worktrees are based on branches, which require a commit history to branch from).

Setting up the demo project

For this tutorial, assume we have a basic React application created with a tool like Vite. The application is a simple to-do list that currently lacks a few key features.

Defining parallel tasks

The goal is to implement three distinct features for the to-do app. Instead of tackling them sequentially, Claude Code will work on all three at the same time, each in its own isolated worktree: dark mode (add a toggle to switch between a light and dark theme), local storage (persist the to-do list in the browser's local storage so that items are not lost on page refresh), and edit todos (add functionality to edit the text of an existing to-do item).

Launching your first worktree session

Starting with the dark mode feature, the key to unlocking this parallel workflow is the -w (or --worktree) flag in the Claude Code command.

Open your terminal in the root directory of your project and run:

claude -w dark-mode-toggle "add a dark mode toggle to this react project"

Breaking down this command: claude invokes the Claude Code CLI, -w dark-mode-toggle is the crucial part (the -w flag tells Claude to create and operate within a new Git worktree, with a descriptive name dark-mode-toggle), and "add a dark mode toggle..." is the initial prompt telling the AI agent what to do.

Claude will now create a new worktree, create a new Git branch associated with it, and begin working on your request within that isolated environment.

Observing the automation behind the scenes

While Claude is working, you can open a new terminal window and inspect what it has done.

First, you'll notice a new directory inside your project root: .claude/worktrees/dark-mode-toggle. This is where the files for your new worktree are physically located. Claude intelligently keeps these isolated worktrees organized within a hidden .claude directory to avoid cluttering your main project folder.

Next, you can run Git commands to see the underlying changes. List worktrees:

git worktree list

You will see your main project directory and the new worktree you just created. List branches:

git branch

You'll see that Claude automatically created a new branch named worktree-dark-mode-toggle.

This is the beauty of the integration. With a single, simple flag, Claude Code handles all the necessary Git commands to create an isolated development environment for your task.

A practical example: implementing three features in parallel

Unleashing the full power of this feature means running multiple sessions. While the first Claude session is working on the dark mode toggle, you can open two more terminal windows and kick off the other tasks.

Launching concurrent agents

In a second terminal, run:

claude -w local-storage "add local storage support to this project so if I refresh my todos still exist"

And in a third terminal, run:

claude -w edit-todos "add the ability to edit todos"

You now have three independent Claude Code agents running simultaneously. Each agent is operating in its own worktree and on its own dedicated branch. They can install packages, modify files, and run development servers without any knowledge of or interference with each other.

The power of isolation: handling a bug gracefully

After the agents have finished their work, reviewing the results reveals the power of isolation. Dark mode works perfectly (the code is isolated on the worktree-dark-mode-toggle branch and is ready for a pull request), edit todos works perfectly (this feature is on the worktree-edit-todos branch and is also ready for review), and local storage has a bug (the application crashes when trying to load from local storage).

In a traditional, monolithic workflow, this bug would block the other two perfectly good features from being released. But with worktrees, the story is different. The buggy code is confined to the worktree-local-storage branch. You can create PRs for the dark mode and edit features and get them merged and deployed.

Meanwhile, you can start a new, dedicated Claude Code session to fix the bug in the isolated local storage worktree without any pressure or impact on the rest of the project. This ability to compartmentalize work is a cornerstone of modern, agile development.

Advanced worktree management and techniques

Claude Code provides several advanced features to make your worktree workflow even more efficient and powerful.

Managing session lifecycle

When you finish a task and exit a Claude session (with Ctrl+C), you are presented with a choice: keep worktree (this preserves the worktree directory and its associated Git branch; this is the default and is useful if you plan to return to the work later) or remove worktree (this cleans up after you, deleting the worktree directory and the associated branch).

To return to a worktree you've kept, simply run the same command you used to create it: claude -w <worktree-name>. Claude is smart enough to recognize that the worktree already exists and will resume the session in that context.

Furthermore, you can use shortcuts to manage your sessions: Ctrl+R opens a fuzzy finder to resume any previous Claude session, and Ctrl+W shows all sessions specifically within the current project, making it easy to jump between different worktrees.

Supercharging your terminal with the tmux flag

For terminal power users, Claude Code offers integration with tmux, a popular terminal multiplexer. By adding the --tmux flag, you can get an interactive shell session inside the worktree's environment:

claude -w edit-todos --tmux "add the ability to edit todos"

This will launch the Claude agent in one pane and give you a shell prompt in another pane, already in the worktree directory. This is incredibly useful for running commands, checking server logs, or performing manual file operations directly within the isolated context of the worktree.

Automating workflows with custom agents and hooks

The worktree integration extends to Claude Code's more advanced automation features, allowing for highly sophisticated workflows.

Custom agent isolation

You can define your own specialized "subagents" in Claude Code. If you want a custom agent to always run in an isolated worktree, you can simply add a line to its definition file.

Create a file at .claude/agents/worktree-worker.md with the following content:

---
name: worktree-worker
model: haiku
isolation: worktree
---

You are a specialized agent that always works in isolation.

Now, whenever this worktree-worker agent is invoked, it will automatically spin up a new worktree for its task, without you needing to specify the -w flag.

Worktree hooks

For ultimate control, Claude Code exposes WorktreeCreate and WorktreeRemove hooks in its settings. These hooks allow you to run any custom shell command when a worktree is created or removed. This enables two powerful use cases: using other version control systems (while the default is Git, these hooks allow you to integrate worktree-like functionality with other VCS tools like Jujutsu or SVN), and automated setup/teardown (you could create a hook to automatically run npm install every time a new worktree is created, ensuring dependencies are always fresh, or to run a cleanup script upon removal).

Navigating a known issue: the feature flag bug

It is important to note that, as a very new feature, the worktree integration has experienced some initial teething problems. Shortly after its release, many users reported that the -w flag was not working as expected. This was likely due to an issue with a remote feature flag that was intended to control the rollout.

The Claude Code team is aware of these issues, and fixes are typically rolled out quickly. If you encounter problems, the first step is always to ensure you are running the absolute latest version of the CLI. While some advanced users found ways to temporarily patch their own Claude Code binary to enable the feature, the recommended approach for most is to wait for the official, stable update.

Final thoughts

Git worktrees are powerful on their own. When combined with Claude Code, they become even more useful.

Instead of juggling branches, stashing changes, and constantly switching context, you can let Claude create clean, isolated environments for each task. This allows you to build features in parallel, fix bugs without blocking other work, and keep pull requests small and focused.

More importantly, this workflow feels lighter. You do not have to think as much about Git mechanics. You do not have to worry about breaking unrelated changes. Each task lives in its own space. It stays clean, organized, and independent.

There may still be small issues as the feature matures. That is normal for something new. Even so, the productivity gains are clear.

In short, Claude Code’s worktree support is not just a small improvement. It changes how you can collaborate with AI while building software. Once you get used to working this way, it is difficult to go back.

Got an article suggestion? Let us know

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.