On this page#
- What are Claude Code worktrees?
- Why do Claude Code worktrees exist?
- How do Claude Code worktrees actually work?
- When do you need worktrees, and when do you not?
- What vendors leave out about worktrees
- FAQ
What are Claude Code worktrees?#
Claude Code worktrees are separate working directories, created with Git’s worktree feature, that let multiple Claude Code sessions work on different branches of the same repository without sharing checked-out files. Each session gets an isolated filesystem view, while the worktrees reuse one repository’s Git history and object database.
A Git worktree is a checked-out branch with its own working directory and index. The main repository directory is already one worktree; git worktree add creates another.
That distinction matters. A worktree is not:
- A second full clone.
- A container or virtual machine.
- A replacement for branches.
- A permission boundary.
- A guarantee that two agents will not make conflicting changes.
Think of it as a branch made physically separate. If one Claude Code session edits authentication code in one worktree while another updates a database migration elsewhere, neither session sees the other’s uncommitted files.
The practical value is isolation without duplicating the entire repository. The practical risk is assuming that filesystem isolation also isolates everything the project touches. It does not.
Photo by Snapwire on Pexels.
Why do Claude Code worktrees exist?#
Worktrees solve a specific problem: branches isolate committed history, but they do not give simultaneous sessions separate checked-out files. Without worktrees, parallel agents in one directory can overwrite files, observe half-finished edits, change the active branch, or run commands against state created by another session.
Before worktrees, engineers generally used one of three approaches:
- Run one task at a time in the main checkout.
- Stash changes, switch branches, and repeatedly restore context.
- Clone the repository again for every parallel task.
The first approach is safe but serial. The second is fragile once an AI agent is issuing commands autonomously. The third works, but duplicates repository administration and makes cleanup less obvious.
The Claude Code overview describes an agent that can inspect a codebase, edit files, and run commands. Those capabilities make directory isolation more important, not less. An agent operating in a shared checkout is not merely sharing source files; it is sharing whatever mutable state the task produces there.
Worktrees give each task a stable branch and directory:
repo/ main branch
repo-worktrees/
billing-fix/ fix/billing
api-refactor/ refactor/api
dependency-update/ chore/dependenciesThat arrangement also improves reviewability. A human can enter any task directory, inspect its diff, run its checks, and discard the worktree without disturbing the main checkout.
If your larger problem is defining safe operating rules for agents—not merely creating directories—the PairFoundry foundations are the more relevant next step. Worktrees provide separation; they do not define acceptance criteria or repository invariants.
How do Claude Code worktrees actually work?#
Claude Code does not create a new Git model. Git creates and manages the worktree; Claude Code simply runs inside that directory and treats its checked-out files as the current repository. The isolation therefore comes from Git’s filesystem layout, not from a special Claude execution sandbox.
A basic setup looks like this:
git worktree add ../repo-billing-fix -b fix/billing
cd ../repo-billing-fix
claudeGit creates the new branch, checks it out in the new directory, and registers that directory with the repository. Starting Claude Code there makes that worktree the session’s project context.
For an existing branch, omit branch creation:
git worktree add ../repo-api-refactor refactor/api
cd ../repo-api-refactor
claudeUse Git to inspect and clean up the registered directories:
git worktree list
git worktree remove ../repo-billing-fix
git worktree pruneThe exact rules for adding, locking, moving, removing, and pruning worktrees belong to the official Git worktree manual. That manual is the authority because Claude Code is consuming the resulting checkout, not redefining it.
Several things are separate per worktree:
- Checked-out files.
- The active branch.
- The index and staged changes.
- Untracked files located inside that directory.
Several things remain shared or externally coupled:
- Repository objects and references managed by the common Git repository.
- Remote branches and pushes.
- Credentials.
- Services such as databases, queues, and local servers.
- Caches or build outputs stored outside the worktree.
- Fixed ports and globally named containers.
This is why “one worktree per agent” is useful but incomplete. Two sessions can edit separate files and still collide because both try to bind the same port, migrate the same development database, or write to the same external cache.
A serious setup pairs each worktree with task-specific runtime configuration:
branch: fix/billing
directory: ../repo-billing-fix
database: app_billing_fix
port: task-specific
cache path: inside the worktree or task-specific
agent scope: billing issue onlyThe Claude Code documentation can tell you how the agent operates. Your repository must still define which commands are safe, which generated files belong in Git, and which checks constitute completion.
Photo by Lukas Blazek on Pexels.
When do you need worktrees, and when do you not?#
Use worktrees when two or more tasks must be active simultaneously and each task can own a branch, directory, and runtime identity. Do not add them merely because worktrees sound more sophisticated; a single focused session in a clean checkout remains the simplest reliable arrangement.
Use a worktree when:
- One agent is implementing while another investigates a separate issue.
- You need to interrupt a long-running change without stashing it.
- Multiple agent sessions would otherwise share uncommitted files.
- You want each task to have a disposable directory.
- A reviewer needs to run one branch while development continues elsewhere.
Do not use a worktree when:
- Only one task is active.
- The tasks must constantly edit the same files.
- Your repository scripts assume one fixed absolute path.
- All sessions must use one non-isolated database or service.
- The extra directories would hide rather than clarify ownership.
A useful decision rule is simple: if you cannot name the branch, directory, owner, and cleanup condition for a task, do not create its worktree.
Worktrees are particularly poor at rescuing badly decomposed work. If two agents need to coordinate every edit, parallel execution creates merge work rather than throughput. Split the tasks along real boundaries first; then isolate them.
For broader workflow choices, the PairFoundry packs provide the relevant grouping of practices. For other concise explanations of agent and engineering terminology, see plain definitions.
What vendors leave out about worktrees#
Worktrees isolate checked-out files, not the whole development environment. The common mistake is to treat them as sandboxes and then discover that agents still share ports, credentials, databases, containers, caches, hooks, or deployment access. That mistake can damage real repository state even when Git behaves perfectly.
The main costs are operational:
- Every worktree needs dependency and build-state handling.
- Every active branch needs an owner and cleanup condition.
- Cross-worktree conflicts still appear when branches merge.
- Large ignored directories may be recreated in every worktree.
- Tooling that assumes the main checkout path may fail.
- Background processes can survive after the worktree is removed.
Git also prevents the same branch from being checked out normally in multiple worktrees. That is a safeguard, not an inconvenience: separate concurrent tasks should not silently claim the same branch.
Removal needs discipline. Commit, preserve, or intentionally discard the task’s changes before removing its worktree. Then stop its processes and clean up task-specific databases, ports, containers, and caches. git worktree remove handles the registered working directory; it does not clean external infrastructure for you.
The right mental model is narrow: a worktree is cheap Git checkout isolation. It is excellent at that job. Calling it a complete agent-isolation strategy is wrong.
Photo by Digital Buggu on Pexels.
Related reading#
- What Cline memory bank actually is, and when you need it
- What is MCP server in AI, explained without the marketing
FAQ#
Does the Claude code support worktrees?#
Yes. Claude Code can run inside a Git worktree because a worktree is a normal checked-out working directory from the tool’s perspective. Git creates and manages the worktree; you start Claude Code from that directory. The official Claude Code documentation covers the agent, while Git defines worktree behavior.
What is a work tree in Claude Code?#
A work tree in Claude Code is a separate Git-managed directory containing one checked-out branch. Running a Claude Code session there keeps that session’s file edits, staged changes, and untracked files separate from sessions in other worktrees, though external services and repository-level operations may still be shared.
What is worktree in coding?#
In coding, a worktree is the directory containing the files for a checked-out Git revision. Git supports one main worktree plus additional linked worktrees, each usually attached to a different branch. They share repository history while maintaining separate checked-out files and indexes.
What is so great about the Claude code?#
Claude Code can inspect a repository, edit files, and run development commands as an agent. Worktrees make those capabilities safer to use concurrently by giving each task a separate checkout. The benefit is not magical code generation; it is faster task execution without forcing unfinished filesystem state into one shared directory.
How do I start a Claude code session in Worktree?#
Create the directory with git worktree add, change into it, and start Claude Code there: git worktree add ../repo-task -b task/branch, then cd ../repo-task, then claude. Before starting, assign separate ports, databases, caches, or containers if the project’s runtime state is not already isolated.