How to Run Multiple Claude Code Agents Safely with Git Worktrees

Running multiple Claude agents in the same repo at the same time is asking for trouble. File conflicts, overwritten work, chaos. Unless you use worktrees. Today's Claude Code tutorial is on using Git Worktrees to safely run multiple agents in your codebase. Let's go.

Git Worktrees are a function of the Git repo, not a function of Claude Code. If you think about Git Worktrees as an orchard, the Orchard Method name makes sense.

• The Orchard: your git repo
• Trees: your git worktrees from the repo
• People working on each tree: subagents
• Harvest (collecting all the fruit): the code written by each agent
• Inventory (looking at the fruit to determine what to keep and what to discard): the merged code

The big takeaway here is that the work happens independently (subagents and the coding), but inventory isn't final until all of the fruit is collected and analyzed (the merge).

What is a Git Worktree

A Git Worktree allows users of a repo to create more than one active worktree branch at the same time. But they're configured with different meta data to separate them logically.

Why use Git Worktrees?

Git Worktrees work well in situations when more than one user will be modifying code in the same repo at the same time, particularly when those changes could impact the same pieces of code.

With Claude Code, multiple subagents, which I covered in A Guide to Agents and Subagents in Claude Code, could be working on the same code in the same codebase at the same time, creating the potential for them to overwrite each other's work. Using a Git Worktree prevents that from happening.

How does Claude Code Use Worktrees?

Claude Code makes it so simple to use worktrees. It might be one of the easiest things to configure in Claude Code. There are two ways to do it:

Prompt Method: In your project, tell Claude Code to set up its agents to use worktrees FrontMatter Method: In your subagent's YAML frontmatter, add this line: isolation: worktree

If you're setting up agents across multiple projects, the Prompt Method may work better for you so that your agent isn't permanently using Git Worktrees on all projects. But if you're concerned that a prompt isn't always enforced, I'd go with the FrontMatter Method to ensure the guardrails are in place.

Real Example

I created a new project in Claude Code that contains one HTML file with one label. The initial value of the label is "Hello World!".

I created two agents using the /agents skill whose purpose is to modify the label in the HTML page. One is called html-label-updater and one is called label-updater. They are both going to modify not only the same HTML file, but the same section of the HTML file.

I modified each agent's YAML frontmatter to include the isolation: worktree directive so that they would work in their own worktree and not overwrite each other's code.

Then I ran them in the background:

❯ Run the two agents in the background. Have the html-label-updater update the label in the HTML file to say              
"html-label-updater" and have the label-updater agent update the label in the HTML file to say "label-updater".           

● Launching both agents in the background now.                                                                            

● 2 agents launched (ctrl+o to expand)                                                                                    
   ├─ html-label-updater (Update HTML label to "html-label-updater")                                                      
   │  ⎿  Running in the background             
   └─ label-updater (Update HTML label to "label-updater")                                                                
      ⎿  Running in the background                               

● Both agents are running in the background in isolated worktrees. I'll let you know when they finish.                    

● Agent "Update HTML label to "label-updater"" completed                                                                  

● The label-updater agent finished — it updated index.html to <label>label-updater</label> in its worktree. Still waiting 
  on the html-label-updater agent.                                                                                        

● Agent "Update HTML label to "html-label-updater"" completed

● Both agents are done. Each worked in its own isolated worktree:                                                         

  - html-label-updater → changed <label>Hello World!</label> to <label>html-label-updater</label> in                      
  .claude/worktrees/agent-a4953ae5/index.html                                                                             
  - label-updater → changed <label>Hello World!</label> to <label>label-updater</label> in                                
  .claude/worktrees/agent-a490230b/index.html

  Since both agents modified the same file (index.html) with different values, their changes are in separate worktree
  branches. You'll need to decide which one to merge into your main working tree (or reconcile them manually).

As you can see, each agent completed and modified the label. Now when we commit, we will have to decide what to do.

❯ commit

Both worktrees have uncommitted changes that conflict (same line, different values). Which change would you like to keep?                                                                                                                   

  1. label-updater → <label>label-updater</label>                                                                         
  2. html-label-updater → <label>html-label-updater</label>                                                            
  3. Both — I can combine them (e.g., two labels on the page)    

I chose option 1 because I wanted to keep the change from label-updater and not html-label-updater. And I don't want two labels on the page, so I didn't choose option 3.

❯ 1                                                                                                                       

● Update(index.html)                                                                                                      
  ⎿  Added 1 line, removed 1 line                                                                                         
       6      <title>Hello World</title>                                                                                  
       7  </head>                                                                                                         
       8  <body>                                                                                                          
       9 -    <label>Hello World!</label>                                                                                 
       9 +    <label>label-updater</label>                                                                                
      10  </body>                                                                                                         
      11  </html>

● Done. index.html now has <label>label-updater</label>.

Summary

In the agentic coding model, just like in software development departments across the world, having more than one person making changes to the same codebase runs a real risk of code being overwritten. Using a git repo isn't enough when the same code must be changed by multiple people concurrently. Adding a Git Worktree to your project is essential to letting you be in control of which changes are applied to the main branch.