Git worktrees: How to work on multiple branches at once
Principal Content Producer
Git worktrees let you check out multiple branches of the same repository in separate directories. Each worktree has its own files and staging area, but they all share the same Git history. You can work on several branches without repeatedly switching between them, stashing changes, or cloning the repository again.
Worktrees are especially useful when working with coding agents. Tools like Claude Code, Codex, and Cursor can use them to handle multiple tasks in parallel without editing the same files. Developers can review the changes separately and merge them when they’re ready.
In this guide, we’ll cover how Git worktrees work, how to use them with coding agents, and how to manage and validate changes when working on multiple tasks at once.
What is a Git worktree?
A Git worktree is a separate working directory linked to an existing Git repository. Each worktree can check out a different branch, so you can keep multiple versions of a project available without switching branches in one folder.
For example, a repository with an additional worktree might look like this:
my-app/ # Original working directory
├── .git/
└── src/
my-app-feature-x/ # Additional worktree
├── .git # File linking to the original repository
└── src/
Both directories belong to the same repository. They share commits, branches, and tags, but the files checked out in each directory are separate. Changes made in one worktree won’t overwrite files in another.
Each worktree has its own staging area, where Git tracks which changes you’ve selected for the next commit. You can edit and commit files in one worktree without including unfinished changes from another.
Git normally allows a branch to be checked out in only one worktree at a time. If you’re working on multiple tasks at once, you’ll generally need a different branch for each one.
Git worktrees vs. switching branches or cloning
Git offers several ways to move between tasks. Switching branches with git switch works well for one task at a time, but switching back and forth can get tedious. If unfinished changes get in the way, you’ll need to commit or stash them, and keeping track of stashed changes can quickly become a hassle.
Cloning the repository gives each task its own directory, but also duplicates Git data and requires separate setup and maintenance.
Git worktrees offer the best of both approaches for parallel development: separate directories that share the same Git history. You can keep multiple branches checked out and move between tasks without disturbing unfinished work.
Here’s how the options compare:
| Approach | How it works | Best for |
|---|---|---|
| Switch branches | Changes the checked-out branch in your current directory | Moving between tasks when your working directory is clean |
| Git stash | Temporarily saves uncommitted changes | Interrupting unfinished work |
| Git worktree | Creates another working directory linked to the same repository | Working on multiple branches at once |
| Second clone | Creates another copy of the repository with its own Git data | Working with independent Git settings or repository state |
For example, you might use a worktree to keep a development server running on one branch while you investigate a bug on another, without disrupting the first directory.
Create and manage Git worktrees
Git has commands for creating, listing, moving, and removing worktrees. For most day-to-day use, you’ll only need add, list, and remove.
Create a worktree for a new branch
To create a branch named feature-x and check it out in a new directory, run:
git worktree add -b feature-x ../feature-x
The command has three parts:
git worktree addcreates a new working directory.-b feature-xcreates a new branch namedfeature-x.../feature-xspecifies where to create the directory. The../places it alongside your current directory.
After running the command, you can open ../feature-x in your editor and start working. The original directory stays on its existing branch, with its files unchanged.
Create a worktree for an existing branch
If the branch already exists, you don’t need -b:
git worktree add ../bugfix-123 bugfix-123
The first bugfix-123 identifies the new directory. The second tells Git which branch to check out.
Git will refuse the command if that branch is already checked out in another worktree. You can use the existing directory or create a separate branch.
List your worktrees
To see all the worktrees connected to your repository, run:
git worktree list
Example output:
/Users/you/my-app 9f2a1c4 [main]
/Users/you/feature-x 3b71e2d [feature-x]
/Users/you/bugfix-123 8c52a1f [bugfix-123]
Each line shows the directory path, the currently checked-out commit, and the branch name in brackets.
The string in the middle, such as 3b71e2d, is a shortened commit hash. For most worktree management tasks, the directory and branch name are what you’ll care about.
Remove a worktree
Once you’ve finished a task and merged its changes, remove the worktree with:
git worktree remove ../feature-x
Git removes the worktree directory and its associated metadata. It doesn’t delete the branch, so the committed changes remain in the repository.
If the worktree contains uncommitted changes, Git will normally refuse to remove it. Check the changes before deciding whether to commit, discard, or move them elsewhere.
Use Git worktrees with coding agents
Worktrees let coding agents work on separate tasks without editing the same files.
For example, you could ask one agent to refactor authentication code and another to update the tests. Each works in its own directory on a separate branch. You can inspect the results independently and decide when to merge them.
Claude Code, Codex, and Cursor support worktree-based workflows, although they differ in how they create and manage worktrees.
| Claude Code | Codex app | Cursor | |
|---|---|---|---|
| Creating worktrees | claude --worktree <name> or isolated subagents |
Managed worktrees for tasks | Agents window or /worktree |
| Default location | .claude/worktrees/ |
$CODEX_HOME/worktrees |
Use git worktree list to find it |
| Bringing changes back | Merge the branch or open a pull request | Create a branch or transfer work to the local checkout | /apply-worktree or create a branch and PR |
| Environment setup | .worktreeinclude |
.worktreeinclude and setup scripts |
.cursor/worktrees.json |
Tool behavior may change with future releases.
These tools handle much of the worktree setup for you. But the resulting directories are still ordinary Git worktrees, so you can inspect, test, and manage them using standard Git commands.
Find and review an agent-created worktree
Agents can run tests and linters in their own inner loop before handing work back, so your job is usually to review what changed, confirm the checks passed, and decide whether to keep the work.
Here’s how to find, review, and check an agent’s changes before merging them and cleaning up the worktree.
1. Find the worktree
From your original repository directory, run:
git worktree list
You might see:
/Users/you/my-app 9f2a1c4 [main]
/Users/you/my-app/.claude/worktrees/auth-refactor 3b71e2d [worktree-auth-refactor]
The second entry identifies a worktree created for an authentication refactor. Its location tells you where to find the files, and the branch name identifies the changes being developed.
2. Review what changed
Before merging the code, check the commits and the changes they contain.
You can inspect another worktree without leaving your original directory by using Git’s -C option. It tells Git to run the command from the specified directory.
To see the changes committed on the agent’s branch relative to main, run:
git -C .claude/worktrees/auth-refactor diff main...HEAD
The diff command shows additions, deletions, and modifications. Here, main...HEAD compares the branch’s current commit (HEAD) with the point where its history diverged from main.
To see which commits were added to the branch, run:
git -C .claude/worktrees/auth-refactor log main..HEAD --oneline
The log command gives you a shorter overview of the work, showing each commit’s identifier and message.
Both commands inspect committed changes. To check whether the agent left any uncommitted work, run:
git -C .claude/worktrees/auth-refactor status
git -C .claude/worktrees/auth-refactor diff
git status shows which files have changed, including staged changes. git diff shows unstaged changes. To inspect staged changes too, use git diff --cached.
3. Confirm the checks passed
Start with the agent’s own test results. If it didn’t run the project’s checks, or you want to verify them yourself, run them in the worktree.
Open the worktree directory in your editor or navigate into it using the terminal.
Because it’s a separate directory, you’ll likely need to install dependencies before running the application. For example, a Node.js project may require npm ci to create its local node_modules directory.
Once the environment is ready, run the project’s normal tests and development commands. Check the agent’s work before bringing it into your main checkout.
4. Integrate the changes
If the worktree has its own branch, you can push that branch and open a pull request. This gives the changes the same review and continuous integration (CI) process as any other contribution.
Some agent tools create worktrees in a state called detached HEAD. Normally, Git associates your checked-out files with a named branch. In a detached HEAD state, they’re associated directly with a specific commit instead.
You can still edit files and create commits in this state, but you’ll generally want to create a branch before integrating the changes:
git switch -c auth-refactor
The command creates a branch at the current commit and checks it out, preserving access to the work in normal branch-based workflows.
Some tools offer their own ways to integrate changes. For example, Codex provides a “Create branch here” action, while Cursor’s /apply-worktree can transfer changes into your main checkout.
5. Remove the worktree
After the changes have been merged and you’ve checked for unfinished work:
git worktree remove .claude/worktrees/auth-refactor
Some coding agents remove old worktrees automatically. Don’t rely on their cleanup behavior to preserve unfinished work. Commit important changes and move them onto a named branch or integrate them before removing the worktree.
Set up dependencies and local services
A new worktree contains your repository’s tracked files, but it may not have everything needed to run the application.
For example, a Node.js project might need its dependencies installed in node_modules, an .env file containing local settings, and a development server running on a particular port. These files and resources aren’t necessarily included when Git creates a worktree.
Coding agents can handle much of the setup, including installing dependencies and preparing project-specific files. Claude Code and the Codex app support .worktreeinclude for copying ignored files into new worktrees, while Cursor can run setup commands defined in .cursor/worktrees.json. Check which files contain secrets before copying them, and give each task only the access it needs.
Keep worktree environments from interfering with each other
Worktrees keep each task’s files separate, but processes running in those directories can still use the same ports, databases, and other services. For example, two development servers can’t both listen on port 3000. Tests can also interfere with one another if they modify the same database.
Here’s what stays separate and what can be shared:
| Separate for each worktree | Shared or potentially shared |
|---|---|
| Working files and staging area | Repository commits, branches, and tags |
| Checked-out branch or commit | Repository-level Git settings and hooks |
| Dependencies installed in each directory | Network ports, databases, and external services |
Git hooks are scripts that run during operations like committing code. Worktrees generally use the same repository-level hooks, although Git supports some worktree-specific settings.
When running tasks in parallel, give development servers different ports and use separate databases or containers if tests could change the same data. Agents can help set up those environments, but worktrees alone won’t keep shared services apart.
Running multiple coding agents at once
A common approach is to give each independent task its own worktree and branch. You can review and merge each task without mixing its unfinished changes with another.
For example, three independent tasks might use:
my-app/
my-app-auth-refactor/
my-app-feature-x/
my-app-bugfix-123/
Each worktree can have its own terminal session, dependencies, and development server. Agents can work on different tasks without modifying one another’s uncommitted files.
Each agent works in its own worktree and branch. When a task is done, its branch goes through CI, where the project’s checks run on that branch independently of the others. The results show which changes are ready and which need more work. You then review the ones that pass and merge them into main.
Worktrees keep the agents’ files separate, but they won’t prevent merge conflicts if two agents change the same code, and they don’t protect shared external resources. So give each agent work that doesn’t overlap, and give each task its own ports and databases where they’d otherwise collide.
If an agent needs stronger isolation, such as a separate operating system environment or restricted access to credentials and services, a worktree alone isn’t enough. An AI sandbox provides additional boundaries around the code and processes being executed.
Manage parallel work without creating more unfinished tasks
Worktrees and coding agents make it easier to work on multiple tasks at once, but more development activity doesn’t necessarily mean faster delivery.
Our 2026 State of Software Delivery Q3 Pulse report found that active feature-branch workflows have increased by roughly 40% since Q1, but delivery velocity has remained flat for the median team. The highest-throughput teams, meanwhile, are managing more workstreams and shipping changes faster.
The challenge is keeping up with the work being produced. A few practices can help:
- Keep tasks small and independent. Choose work that can be completed and merged without extensive coordination.
- Limit work in progress. Don’t start more tasks than the team can realistically review, test, and merge.
- Merge regularly. Long-lived branches are more likely to conflict with changes made elsewhere.
- Clean up finished worktrees. Remove directories after merging so it’s easier to see what’s still in progress.
For larger changes, stacked pull requests can help break work into smaller, dependent PRs that can be reviewed and merged individually.
Validate changes before merging
Each worktree can have its own branch, so developers and agents can test changes independently through CI before merging them into main.
Give coding agents access to CI results
When a branch fails CI, coding agents need to know what went wrong before they can fix it. Without access to the results, developers may have to retrieve logs, find the relevant errors, and pass that information back to agents.
CircleCI’s CLI and MCP tools give agents access to pipeline results, test failures, and build logs. The CLI’s --failure-report option collects failure information across jobs in one call, so agents can investigate problems and propose fixes. Developers can review the changes and direct further validation before merging.
For faster feedback, Chunk lets agents validate local code changes in isolated environments before pushing them to the repository.
Common Git worktree errors
Git has a few safeguards to prevent problems with branches and worktree directories. Most errors are straightforward to fix once you know what’s causing them.
| Error | What it means | How to fix it |
|---|---|---|
fatal: 'feature-x' is already checked out |
Another worktree is using the branch | Open the existing worktree or create a different branch |
cannot delete branch ... used by worktree |
The branch is still checked out | Remove or switch the associated worktree before deleting the branch |
Worktree appears as locked |
Git has been told to preserve it, possibly by an agent tool | Confirm it’s no longer in use, then run git worktree unlock <path> |
| Deleted worktree still appears in the list | Git still has a record of a directory that no longer exists | Run git worktree prune |
Avoid using --force to bypass worktree protections without understanding the problem. Those protections help prevent conflicting branch checkouts and accidental loss of work.
Keep parallel development moving
Git worktrees give developers and coding agents a practical way to work on multiple branches without interfering with one another. Each task has its own space, making it easier to develop changes independently, review the results, and bring them back into the main project.
As more agents work in parallel, keeping up with testing and integration becomes increasingly important. CircleCI gives agents access to CI results and failure context so they can investigate problems and propose fixes without developers having to gather every log by hand.
Ready to add CI to your agent workflow? Sign up for CircleCI for free, or install the CircleCI CLI and ask your coding agent to run circleci onboard to help set up your project.
