Running Claude Code sessions one after another is a habit, not a requirement. When your tasks are genuinely independent, there is no reason one has to wait for the other. Git worktrees give each Claude session its own checked-out directory on its own branch, all drawing from the same .git object store. No duplicate clones, no file conflicts, standard git merge when you are done. This post walks through the full workflow: when to reach for a worktree, how to set one up, what isolation you actually get (and what you do not), and how to clean up without losing work that hasn't been committed yet.
When a Worktree Helps
Not every task warrants one. Honest answer: worktrees shine in a fairly specific band of situations.
A YouTube walkthrough by bri (June 2026) puts it well. Use a worktree when you have two or more tasks that do not share the same files, or when a task is risky enough that you want to see two different approaches before committing to either. If a single task spans the whole codebase, stick to one session. Same goes for exploratory work where you want the agent to roam freely.
The other good use case: speculative work. Spin up three worktrees, give each a slightly different prompt for the same problem, and pick the version you like. Zylos Research notes that this pattern has become common on teams running four or more concurrent AI sessions, precisely because you are hedging against non-deterministic model output rather than relying on a single pass.
Conversely, if your project involves a large TypeScript monorepo with PostgreSQL, Redis, multiple internal packages and a Remix frontend, worktrees alone will not solve your coordination problems. Trigger.dev wrote about exactly this and eventually moved to a different approach. The filesystem isolation is real. The service isolation is not automatic.
Create Isolated Task Checkouts
Start on your base branch and pull latest. Then add .claude/worktrees to your .gitignore once:
echo ".claude/worktrees" >> .gitignore
Claude places worktrees inside your repo directory by default. Without that .gitignore entry, they show up as untracked files and clutter your git status. Add it, commit it, forget it.
Now spin up a session per task. Open two terminals:
claude --worktree feature-payments
``
claude --worktree bugfix-auth
According to Dan Does Code's write-up, Claude creates the worktree at .claude/worktrees/feature-payments/, checks out a new branch, and scopes the session to that directory. Your main working tree is untouched throughout. You can also use the short flag form claude -w feature-payments if you prefer. Skip the name entirely and Claude auto-generates one.
Each session now operates in complete filesystem isolation. The agent in Terminal 1 cannot touch the files the agent in Terminal 2 is working on, because they are in different directories on different branches. That is the whole trick. It is infrastructure-level separation, not coordination logic between agents. (The Claude Code subagents guide covers the orchestration side if that is what you are after instead.)
Giving Each Session Its Task
Once both sessions are running, give each one its instructions. Treat each Claude instance as a fresh context. Be specific about scope. If Terminal 1 is building a payments feature, tell it which files to touch and which to leave alone. Same for Terminal 2.
When a session finishes, ask Claude to push the branch and open a pull request before you close the terminal. That way the work is safely off your local machine and ready to review.
Manage Dependencies, Ports and Local Configuration
This is where things get fiddly. Filesystem isolation is automatic. Everything else requires a bit of manual setup.
Ports. If both worktrees spin up a dev server, they will collide on the same port by default. The fix is to give each worktree its own .env file with a different port assignment. Something like PORT=3001 in one and PORT=3002 in the other. Or pass the override inline at startup. Either works.
Databases. SQLite is easy: point each worktree's .env at a different file path. PostgreSQL or MySQL requires more thought. You need either a separate database instance per worktree, or at minimum a separate schema/database within the same instance. Configure the connection string via environment variables in each worktree's .env. Do not share a database between two agents writing migrations concurrently. That is asking for corruption or race conditions.
Local config files. If your project uses a local config file that is not committed (things like .env.local , config/local.yml), you will need to create one per worktree. They do not inherit from the main working tree automatically.
MindStudio's guide on parallel AI coding agents covers these isolation patterns in more detail. The short version: worktrees give you branch and directory isolation by design. Database and port isolation require you to configure it explicitly, upfront.
One more thing worth flagging here. If you are working on a project with expensive or complicated local service setup and you are running multiple worktrees, consider whether the setup cost is worth the parallel speedup. For a library or CLI tool, absolutely. For a full-stack monorepo with six services, maybe less so. If you want help scoping that out, a Claude Code developer can assess whether worktrees or a different parallel strategy fits your stack.
Review and Integrate Both Branches
Both agents have finished. Both branches are pushed. Now you review.
The workflow here is standard git. The parallel setup does not change the merge process at all. A numbered sequence for a typical two-task repo:
- Check out
mainand pull latest. - Review the first branch.
git diff main..feature-paymentsgives you a full picture of what changed. - If you are happy with it, merge or rebase into
main. Resolve any conflicts with the base branch the usual way. - Pull
mainagain to get those changes. - Review the second branch.
git diff main..bugfix-auth. - Merge. If the two agents touched overlapping files (which should not happen if you scoped tasks correctly, but sometimes does), resolve conflicts here.
- Run your test suite against
mainonce both merges are in.
The advantage of reviewing sequentially like this, rather than merging both simultaneously, is that conflicts from one merge do not compound into the next. Simpler diffs, easier reasoning.
Clean Up Without Losing Uncommitted Work
Cleanup is where developers get nervous. What if there is work in a worktree that was never committed?
The answer: stash it before removing the worktree.
If you have uncommitted changes in a worktree you want to preserve, navigate into that worktree directory and run:
git stash push -m "wip: payments feature - pre-cleanup"
That stash lives in the shared .git object store, which means it is accessible from your main working tree or any other worktree after the original worktree is removed. Once you have stashed, you can safely delete:
git worktree remove .claude/worktrees/feature-payments
Then, back in your main working tree, pop the stash:
git stash pop
If the experiment failed entirely and you want nothing from it, just delete without stashing. git worktree remove with the --force flag removes the worktree even if it has uncommitted changes. Be certain before you use --force. There is no recovery path.
After removing all worktrees, prune the list to keep things tidy:
git worktree prune
That removes any stale administrative references from .git/worktrees/.
Shared Resources That Worktrees Do Not Isolate
Worth being explicit about this, because the mental model of "isolation" can mislead you.
What worktrees do isolate:
- The working directory and all files in it
- The branch each session operates on
- Staged and unstaged changes
What worktrees do not isolate:
- The
.gitobject store (shared by design) - Machine-local auto memory (the official memory docs confirm that same-repository worktrees share this)
- External services: databases, queues, caches, any networked dependency
- Environment credentials and API keys unless you explicitly set different values per worktree
- Anything in your OS-level shell environment that both sessions inherit
This matters for security too. Worktrees are not a tenant boundary. If both sessions share the same API key or database credentials, they share access. Do not treat a worktree as a way to sandbox a Claude session from sensitive local config. It is not that.
For orchestrating multiple agents across a broader workflow rather than just filesystem isolation, the Claude Code superpowers post gets into the wider patterns.
FAQ
Does `claude --worktree` work the same as running `git worktree add` manually?
Functionally similar but not identical. claude --worktree does the git worktree add , creates the branch, and scopes the Claude session to that directory in one step. If you run git worktree add manually and then start Claude inside the resulting directory, you get the same filesystem result but without Claude's built-in scoping. The --worktree flag is the faster path for the common case.
Can I run more than two worktrees at once?
Yes. There is no hard limit imposed by git or Claude Code on the number of worktrees. The practical limit is your machine's RAM and CPU. Each Claude session is a separate process with its own context. Three or four concurrent sessions on a modern dev machine is fine. More than that and you are likely hitting resource constraints before you hit any git limitation.
What happens to a worktree's branch if I delete the worktree?
The branch survives. git worktree remove deletes the working directory and the administrative reference in .git/worktrees/. The branch itself remains and is accessible from your main working tree or any other worktree. You delete the branch separately with git branch -d branch-name when you no longer need it.
Do worktrees affect how Claude reads or writes `CLAUDE.md` project memory?
Same-repository worktrees share machine-local auto memory according to the official memory documentation. If you have a CLAUDE.md file committed to the repo, each worktree reads it from its own checked-out copy. Edits one agent makes to CLAUDE.md in its worktree stay isolated to that branch until merged. But the machine-local layer is shared, so instructions written there by one session are visible to another.
Is there a performance cost to running worktrees versus separate clones?
Worktrees are cheaper than clones. They share the .git object store, so there is no duplication of the entire repository history on disk. The main cost is the working directory itself, which is a full checkout of all tracked files at the branch's current state. For large repos with binary assets or generated files, that checkout size can add up. But the git operations (fetch, log, diff) all run against a single object store, so they are fast.
The cleanest reason to prefer worktrees over separate clones: stashes and refs created in one worktree are immediately accessible everywhere else in the same repo. That shared state is exactly what makes the cleanup workflow above work.