What Git worktree Claude Code actually is, and when you need it

On this page#

• The definition
• Why it exists
• How it actually works
• When you need it and when you do not
• The part vendors leave out
• FAQ

The definition#

A git worktree Claude Code setup gives each Claude Code session its own checked-out working directory and branch while sharing the repository’s underlying Git object database. It is not a Claude-specific version-control system; it is the standard git worktree mechanism used to isolate concurrent agent tasks without cloning the repository repeatedly.

The naming causes unnecessary confusion. Claude Code is the coding agent; Git worktree is the isolation primitive. The same arrangement works with Codex, Cursor, a human developer, or any process that can operate inside a Git repository.

A useful mental model is:

• One repository history
• Multiple working directories
• One checked-out branch per worktree
• One agent task assigned to each directory
• Explicit integration through commits, merges, rebases, or cherry-picks

That is all it is—and that simplicity is its strength.

Photo by Snapwire on Pexels.

Why it exists#

Worktrees solve workspace contention: two agents cannot safely make unrelated changes in the same working directory when they may edit, delete, format, or regenerate overlapping files. Before worktrees, engineers either serialized tasks, repeatedly stashed changes, created full clones, or accepted that concurrent sessions could corrupt each other’s context.

A single Claude Code session can work perfectly well in an ordinary checkout. The problem appears when you start a second task before the first one is cleanly committed.

Without isolation, both sessions observe the same filesystem state. That creates several predictable failures:

• Agent B treats Agent A’s uncommitted edits as existing project code.
• One task runs a formatter across files another task is editing.
• Switching branches changes the filesystem underneath an active session.
• Generated files, dependency state, and test artifacts leak between tasks.
• A “cleanup” command removes files that belong to the other task.

Claude Code’s official documentation explains the product’s capabilities, but the safety boundary still comes from Git and the filesystem. An agent does not own a branch merely because its prompt says so.

Before git worktree, a separate clone was the cleanest robust option. Clones still work, but they duplicate more repository data and make it easier for remotes, hooks, configuration, or branches to drift. Stashing is worse for parallel work: a stash pauses one mutable workspace; it does not create two isolated ones.

The right reason to adopt worktrees is therefore not “agents are fast.” It is that concurrent tasks require separate filesystem ownership.

How it actually works#

Git creates an additional working directory connected to the same repository, then records administrative metadata so each worktree has its own checkout state. The worktrees share objects and repository history, but they do not share the files currently checked out, the index, HEAD, or uncommitted changes.

A minimal setup looks like this:

git worktree add ../repo-auth -b agent/auth
git worktree add ../repo-billing -b agent/billing

You then start one Claude Code session inside ../repo-auth and another inside ../repo-billing. Each session edits its own files and commits to its assigned branch. The authoritative behavior—including branch restrictions and cleanup—is defined by the git worktree manual.

The mechanism has four important consequences.

1. Uncommitted edits are isolated. A change in the authentication worktree does not appear in the billing worktree.

2. Commits are shared immediately. Because both worktrees use the same repository object store, a commit created in one is available to Git operations in the other.

3. Branches remain the integration boundary. Files do not magically synchronize. You must merge, rebase, or cherry-pick completed work.

4. The main repository is not a coordinator. Git tracks worktrees, but it does not schedule agents, assign ownership, detect semantic conflicts, or decide which implementation should win.

A disciplined workflow is deliberately boring:

1. Start from a known base commit.
2. Create one branch and worktree per bounded task.
3. Launch the agent from that worktree’s root.
4. Require tests and a coherent commit before integration.
5. Review the diff against the intended base.
6. Integrate the branch.
7. Remove the worktree only after its useful changes are preserved.

The Claude Code overview describes an agent that can inspect a codebase, edit files, and run development workflows. Worktrees do not change those abilities. They change which filesystem state the agent is allowed to see and mutate.

Configuration files deserve special attention. Tracked instructions appear in every worktree at the selected commit, while ignored local files may not. If a session needs environment variables, credentials, dependencies, or generated configuration, provision them explicitly. Blindly copying an entire local environment into every worktree defeats part of the isolation you created.

For broader operating conventions—task boundaries, review gates, and agent-ready repository foundations—use PairFoundry’s foundations guide. Worktrees provide separation; they do not provide process.

Photo by panumas nikhomkhai on Pexels.

When you need it and when you do not#

Use worktrees when two or more tasks must remain active at the same time and each task can own a branch-shaped unit of change. Skip them when work is sequential, tightly coupled, or dominated by shared external state that separate directories cannot isolate.

| Situation | Use a worktree? | Reason | |---|---:|---| | Two agents changing unrelated subsystems | Yes | Separate files, indexes, and branches prevent accidental contamination | | One agent working while you review another branch | Yes | Review and implementation can remain checked out simultaneously | | A long-running refactor beside an urgent fix | Yes | The fix does not require stashing or disturbing the refactor | | One short task at a time | No | A normal branch adds less operational overhead | | Two agents editing the same core files | Usually no | Filesystem isolation postpones the conflict; it does not resolve it | | Tasks sharing one mutable database or service | Not by itself | The dangerous state exists outside Git | | Throwaway exploration with no concurrent work | Usually no | A temporary branch may be sufficient |

A practical threshold is simple: if starting task B would otherwise require stashing task A, switching away from it, or asking an active agent to stop, create another worktree.

Do not create worktrees merely to look sophisticated. Every additional workspace carries dependencies, build outputs, environment setup, branch cleanup, and review obligations. Parallelism without task independence produces more reconciliation work, not more throughput.

If you are standardizing a team workflow, define the task packets before defining the worktree commands. PairFoundry’s pack overview is the relevant next step when the missing piece is a repeatable operating package rather than another Git alias.

The part vendors leave out#

Worktrees isolate checked-out files, not the whole development system. Agents can still collide through ports, containers, caches, databases, cloud resources, package-manager state, credentials, and generated artifacts stored outside the worktree. Treating a worktree as a sandbox is a category error.

The most common misconception is that one worktree per agent makes parallel changes safe. It only makes them mechanically separate. Two branches can independently pass tests and still conflict semantically when integrated.

The costs are concrete:

• Dependencies may need to be installed per worktree.
• Build caches can consume substantial disk space even when Git objects are shared.
• Repository hooks and local configuration may behave differently than expected.
• Long-lived worktrees drift from the base branch.
• Agents can choose incompatible designs without touching the same lines.
• Removing a directory manually can leave stale worktree metadata.
• A deleted worktree can take uncommitted work with it.

Use Git’s own removal and repair operations as documented in the official worktree manual. Do not treat a worktree directory as disposable until git status is clean and every valuable commit exists on a branch you intend to retain.

Teams also need ownership rules. Name the branch, task, expected files, validation command, and integration owner before launching the session. If two tasks need the same migration, schema, lockfile, or central interface, sequence them or establish an explicit dependency. “The agents will sort it out” is not a workflow.

This distinction—tool capability versus operational guarantee—is central to PairFoundry’s plain definitions. A worktree is excellent branch-level workspace isolation. It is not a security boundary, a container, a task planner, or a substitute for review.

Photo by Christina Morillo on Pexels.

Related reading#

• Claude Code SDK, explained without the marketing
• MCP server meaning: the definition, and the part vendors leave out

FAQ#

How is this different from Claude Code’s official workflow?#

Claude Code provides the agent workflow; Git provides worktree behavior. A Claude Code git worktree convention combines them by launching each session in a separate Git-managed directory. The official product does not turn worktrees into sandboxes or remove the need for branch ownership, testing, review, and deliberate integration.

What is the safest way to roll back a failed agent task?#

Keep the task on its own branch, inspect its status, and preserve any changes worth reviewing before removal. If nothing is valuable, delete the task branch and remove the worktree through Git. Never erase the directory first when uncommitted work might be the only copy.

Can multiple engineers share the same worktree?#

They should not share one filesystem worktree for concurrent editing. A worktree is an ownership boundary, so assign it to one active task or operator. Engineers can share the resulting branch through the remote repository, but simultaneous access to the same directory recreates the contention worktrees were meant to prevent.

When should a team avoid worktrees entirely?#

Avoid them when tasks overlap heavily, developers work strictly sequentially, or the real contention lives in shared databases, services, ports, or deployment environments. In those cases, more directories add ceremony without isolating the dangerous state. Fix task decomposition or external-environment isolation first.

Do worktrees eliminate merge conflicts between agents?#

No. They prevent agents from overwriting each other’s uncommitted filesystem changes, but independent branches can still produce textual or semantic conflicts. Worktrees move conflict handling to an explicit integration step, which is better—but integration still requires tests, code review, and a human decision when designs disagree.