Git Worktrees With Claude Code: Run Parallel Tasks Without Conflicts

Git Worktrees With Claude Code: Run Parallel Tasks Without Conflicts

To use Git worktrees with Claude Code, create one worktree per task, each with its own branch and its own folder, and open a Claude Code session inside each folder. The sessions then never edit the same files at the same time, and you review each result separately before merging into the main branch.

Key takeaways

• A worktree is an extra working folder for the same repository, with its own branch. It isolates the files being edited, not the whole environment.
• One Claude Code session per worktree keeps two tasks from touching the same files or switching the branch out from under each other.
• The isolation holds while the work is in progress. Logic conflicts can still appear at merge time, so review and merge order matter.
• Dependencies, environment variables, ports and shared databases still need attention in every folder.
• Each task needs a written scope, a test command and an acceptance criterion before the session starts.

What is a Git worktree, and why does it prevent conflicts between sessions?

Normally, a Git repository has one working folder and one active branch in it. If you open two Claude Code sessions in that same folder, both read and write the same files. One can read a file the other left half-edited, or one can switch branches while the other is still working. The result is a mix of changes that is hard to separate afterward.

The official Git documentation describes git worktree as the way to keep several working trees attached to the same repository. History and objects are shared. Each folder has its own files and its own index, and a given branch normally cannot be checked out in two worktrees at once. That is exactly the protection parallel execution needs.

The alternative is to clone the repository several times. It works, but it duplicates history and forces you to keep each copy in sync. A worktree is lighter and keeps everything connected, including listing and removing the folders later.

When is it worth running tasks in parallel, and when is it not?

Parallel work only helps when the tasks are truly independent. A simple decision guide:

• Parallelize when the tasks touch different areas of the code, such as a calculation fix, a wording change and a documentation update.
• Parallelize when each task has its own test or check that tells you it is done.
• Parallelize when you can review each result without depending on the others.
• Do not parallelize when two tasks change the same module, the same configuration file or the same database schema.
• Do not parallelize when the second task depends on a decision made in the first. Do those in sequence.
• Do not parallelize when you do not have time to review. Three unreviewed results are worse than one reviewed result.

The real bottleneck is usually your attention for review, not the speed of the AI. Start with two tasks, not five.

How do you create the worktrees and start Claude Code in each one?

The steps below use only Git's own commands. The Claude Code documentation also describes using worktrees for parallel sessions, and some versions may offer shortcuts for it. Check the documentation for the version you use before relying on a shortcut.

• Step one: in the main repository, confirm the main branch is clean and up to date, using git status and git pull.
• Step two: create one worktree per task, in a folder next to the repository, with a new branch. Example: git worktree add ../myapp-invoice -b fix/invoice-calculation
• Step three: repeat for the other tasks, each with its own folder and branch. Prefer folders outside the repository so the main folder's git status stays clean.
• Step four: prepare the environment in each folder. Install dependencies, copy the environment variables you need and confirm the basic test runs.
• Step five: open one terminal per folder, go into it and start claude. Hand over a written scope: the goal, the files it may change, the test command and what it must not do.
• Step six: keep track of the whole set with git worktree list, which shows each folder and its associated branch.
• Step seven: when a task finishes, review it (next section), merge it and remove the worktree with git worktree remove followed by the folder path. Then delete the merged branch.

If you repeat the same scope every week, turn it into a reusable instruction. The article on Claude Code skills shows how to standardize this for a team.

What does a worktree not isolate?

A worktree separates versioned files. A lot of what affects the outcome sits outside that, and this is where unexpected conflicts come from.

• Untracked files: the environment variables file and installed dependencies do not come along. Each folder needs its own setup.
• Ports: two development servers trying to use the same port will collide. Assign one port per worktree.
• Databases and services: if every worktree points to the same development database, one task's migration affects the others. Use separate test databases, or avoid running schema-changing tasks in parallel.
• External effects: a session that sends real messages, calls APIs or writes to company systems acts on the world, not just on the folder. Use test credentials and staging environments.
• AI context: each session has its own context window and does not know what the other decided. If a decision applies to both, write it into both scopes. See more in what a context window is.
• Permissions: running several sessions multiplies what can be executed on your machine. For AI-generated code, consider a restricted environment, as described in sandboxing AI-generated code.

How do you review each result before merging?

Review is what makes parallel work safe. Treat each branch as if it came from a new person on the team: useful, but not trusted by default. A checklist per worktree:

• Read the full diff against the main branch, for example with git diff main...fix/invoice-calculation. Look for changed files that were not in scope.
• Confirm the change solves what was asked, not just that the test passes.
• Run the test suite inside the worktree itself and check that the new tests make sense. The piece on AI-generated tests explains how to avoid tests that only confirm the code's own behavior.
• Look for unwanted changes: configuration files, added dependencies, secrets, broad deletions.
• Check effects outside the repository: migrations, external calls, messages sent.
• Ask a human on the team to approve changes that touch money, personal data or customer communication.
• Only then merge, preferably through a pull request, so there is a record of who approved.

On order: merge one branch at a time. After each merge, update the other branches from main and run the tests again. If there is a conflict, resolve it with the person responsible for the business decision. Do not let the AI choose on its own which version wins.

What does this look like in practice? (illustrative scenario)

Imagine a small team that maintains the internal system of an online store. On Monday there are three requests: fix an error in an invoice calculation, adjust the wording of a notice sent to customers, and update the installation documentation.

The person in charge creates three worktrees, each with its own branch. For the invoice task, the scope lists which files may change and requires a test that reproduces the error. For the notice task, the scope forbids sending real messages and asks only for a change to the template text. The documentation depends on nothing.

When the three sessions finish, review starts with the invoice, because it involves money. The diff shows the session also touched a configuration file outside the scope. The reviewer asks for that part to be reverted, runs the tests and merges. The documentation goes in next. The notice waits until the next day for approval from whoever owns customer support, since the text reaches the customer. No task blocked another, and nothing was merged without a human look.

For outbound messages on channels such as WhatsApp, it is also worth checking the rules on templates and consent in WhatsApp outbound messages: templates and opt-in.

How does this method fit the way we work?

The same reasoning we use to bring AI into business processes applies to parallel development. Map: list the tasks and find out which ones touch the same areas. Limit: define allowed files, test credentials and forbidden actions for each session. Pilot: start with two real tasks, record what worked and what needed rework, and agree on a simple success criterion, such as changes reviewed without surprises. Transfer: document the procedure so the team can repeat it without depending on whoever set it up, and decide whether to expand, adjust or stop.

It helps to separate what is official documentation (Git's commands and how worktrees behave), what is implementation experience (merge order, risk-based review) and what is hypothesis (how many parallel sessions your team can review well). That last one can only be learned by testing in your own context.

Frequently asked questions

Do I need a special Claude Code command to use worktrees? Not necessarily. Worktrees are a Git feature, and you only need to start Claude Code inside each worktree's folder. Some versions of the tool may include shortcuts, so check the official documentation for your version.

Can I have two sessions on the same branch in different worktrees? By default, Git does not allow the same branch to be checked out in two worktrees at once, precisely to prevent concurrent edits. The recommended path is one branch per task, merged after review.

Does a worktree eliminate all merge conflicts? No. It prevents conflicts during editing, but two branches that change the same lines will still conflict when you merge. That is why the advice is to pick independent tasks, merge one at a time and run the tests after each merge.

How do I clean up worktrees when I am done? After merging, use git worktree remove with the folder path and delete the merged branch. If a folder was deleted by hand, the git worktree prune command cleans up the orphaned records left behind.

Sources

• Git: documentação do git worktree
• Anthropic: Claude Code, fluxos de trabalho comuns
• Anthropic: Effective harnesses for long-running agents