Claude Code Worktrees: How to Run Two AI Agents on the Same Codebase at the Same Time
Most people run one Claude Code session at a time. That is the default. It is also a bottleneck.
If you are fixing a bug, you cannot simultaneously work on a new feature. If you are running a long refactor, nothing else moves. You finish one thing, then start the next.
Git worktrees break that constraint. With worktrees, you can run two completely independent Claude sessions on the same repository, in parallel, without them interfering with each other. Different branches, different working directories, full isolation.
Here is exactly how I set this up and why it matters.
What Git Worktrees Actually Are
A git worktree is a second checkout of your repository that shares the same .git directory. Both checkouts see the same history, the same branches, the same remotes. But they can be on different branches, with completely separate working files.
The normal situation: one directory, one branch, one state at a time.
With worktrees: two directories, two branches, running simultaneously.
You already have this capability in git. Claude Code makes it useful.
The Problem Worktrees Solve for Claude Code
When you run Claude Code, it reads and modifies files in your working directory. If you have two tasks and you want to run them in parallel - say, a bug fix on main while building a feature on feature/checkout - you cannot do that with one checkout.
You could clone the repo twice. That works but it is messy: two .git directories, sync problems, risk of working on the wrong copy.
Worktrees give you the clean version: same repository, multiple checkouts, no duplication of git history.
If you want to see how I combine worktrees with scheduled tasks and automation, I cover the full workflow in my free Claude Code toolkit.
[Get the Claude Code automation toolkit - free]
How to Set Up a Worktree
The setup is three commands.
# Create a new worktree for a branch
git worktree add ../my-project-feature feature/new-checkout
# Or create the branch at the same time
git worktree add -b feature/new-checkout ../my-project-feature main
# See all your active worktrees
git worktree list
The first argument after add is the directory path. The second is the branch name.
You now have two directories:
-
my-project/- your original, on whatever branch it was -
my-project-feature/- the new worktree, onfeature/new-checkout
Open a terminal in each. Run Claude Code in each. They run fully independently.
Practical Use Case: Bug Fix in Parallel with Feature Work
This is the scenario that makes worktrees essential.
You are halfway through building a new feature. A critical bug gets reported in production. You need to patch main right now, but you cannot abandon your feature work.
Without worktrees:
- Stash your feature changes
- Switch to
main - Fix the bug
- Switch back to your feature branch
- Unstash
- Hope nothing conflicted
With worktrees:
- Open a new terminal
git worktree add ../my-project-hotfix main- Start Claude Code in that directory
- Fix the bug without touching your feature work
Your feature session keeps running. The bug fix session is completely isolated. No stashing. No branch switching. No risk of contaminating one context with the other.
Use Case: Parallel Claude Sessions for Independent Modules
If your project has clear module boundaries - say, a frontend directory and a backend directory that rarely touch each other - you can run one Claude session optimizing the API while another session rewrites the frontend components.
# Backend session
git worktree add ../my-project-backend main
cd ../my-project-backend
# Frontend session (same branch is fine since they touch different files)
git worktree add ../my-project-frontend main
cd ../my-project-frontend
Both are on main. Both can commit. Because they are touching different files, there are no conflicts. You get double the throughput on the same codebase.
This is where Claude Code stops being a single-threaded tool and starts behaving like a team.
Worktrees Inside Claude Code (The Built-In Way)
Claude Code has native worktree support. When you start a session, you can pass --worktree to isolate that session in a dedicated worktree automatically.
More useful: Claude Code's agent tool accepts an isolation: "worktree" parameter. When a sub-agent runs in worktree isolation, Claude Code:
- Creates a temporary worktree on a new branch
- Runs the agent's changes in that isolated space
- Returns the worktree path and branch name when done
- Cleans up automatically if the agent makes no changes
This means you can run parallel agents in the same Claude session with zero manual git setup.
Agent({
isolation: "worktree",
prompt: "Refactor the authentication module to use JWT",
...
})
That agent runs completely isolated. You can run three of these simultaneously, each touching a different part of the codebase.
Cleaning Up
When you are done with a worktree:
# Remove the worktree
git worktree remove ../my-project-feature
# If there are uncommitted changes you want to drop
git worktree remove --force ../my-project-feature
# Remove stale worktree references
git worktree prune
Clean up as you go. Active worktrees are listed in git worktree list. It is easy to lose track of them if you create several.
What to Watch Out For
Shared files: Some files are shared across worktrees - the .git directory and anything that lives there. Git config, hooks, and the index are per-worktree, but objects and refs are shared. If two Claude sessions both try to modify the same branch ref, you will have a conflict.
Lock files: package-lock.json, yarn.lock, and similar files in the root will cause conflicts if two worktrees try to run installs simultaneously. Pin dependencies or use separate node_modules directories.
Environment variables: Each terminal running Claude Code will use whatever environment variables are set in that terminal. If you have different .env files for different contexts, set them per session explicitly.
The short version: keep worktrees on different branches when in doubt. Same branch is fine for truly independent modules, but different branches give you cleaner isolation.
The Real Value
The point of worktrees is not complexity. The point is that your bottleneck is rarely Claude Code itself - it is the linear, one-thing-at-a-time nature of how most people use it.
Worktrees unlock parallel work. Bug fixes without stopping feature development. Independent modules moving simultaneously. Sub-agents running in isolation without stepping on each other.
If you are running any serious project with Claude Code and you are not using worktrees, you are leaving throughput on the table.
Want the full workflow? I run a multi-session Claude Code setup across a live ecommerce operation, content pipeline, and analytics stack. The automation toolkit covers all of it, including worktree templates.
[Download the Claude Code workflow toolkit - free]
What to Read Next
If you are new to running multiple Claude sessions, start with understanding sub-agents first:
- How I Use Claude Code Sub-agents to Run Parallel Tasks
- Claude Code Hooks: The Feature That Runs Your Project Automatically
Worktrees plus sub-agents plus hooks is the full setup. Once all three are running, Claude Code operates more like a team than a single assistant.
Top comments (0)