Git Worktree: What It Is, How to Use It, and When To

A git worktree is a second working directory attached to the same repository, with its own branch checked out. One repo, several folders, one shared history. You create one with git worktree add <path> <branch>, work in it like any normal checkout, and remove it with git worktree remove <path> when you’re done.

That means you can have main open in one folder and a feature branch open in another, at the same time, without stashing, without switching, and without cloning the repo again.

What is a git worktree?

Normally, a git repo has one working directory. You can only have one branch checked out at a time. To work on a different branch, you stash or commit your changes, switch branches, and switch back when you’re done.

A worktree creates a second (or third, or fourth) working directory linked to the same repo. Each worktree has its own branch checked out. Changes in one worktree don’t affect the others.

# You're on main in your project
cd ~/projects/my-app

# Create a worktree on a new branch
git worktree add ~/projects/my-app-feature feature/new-api

# Now you have:
# ~/projects/my-app/          → main branch
# ~/projects/my-app-feature/  → feature/new-api branch

Both directories share the same git history, but each has its own files and branch. Editing a file in one directory doesn’t change it in the other.

A worktree sits between a branch and a clone. A branch gives you one working copy you switch in place. A clone gives you a second copy with its own history. A worktree gives you a second copy that still shares the one history, which is why it’s cheap: only the checked-out files take extra disk.

How to use git worktree

git worktree add

git worktree add is the command you’ll use most. It takes a path for the new directory and a branch to check out there.

# Create a worktree on a brand-new branch
git worktree add ../my-app-feature -b feature/new-api

# Create a worktree from a branch that already exists
git worktree add ../my-app-hotfix hotfix/login

# Create a worktree from a specific commit or tag (detached HEAD)
git worktree add ../my-app-v2 v2.0.0

Two things to know up front. Put the worktree outside your main repo directory (the ../ above), or your editor and build tools will treat it as part of the project. And git won’t let the same branch be checked out in two worktrees at once, so each one needs its own branch.

The rest of the command set

# List all worktrees, with their paths and branches
git worktree list

# Remove a worktree (after merging)
git worktree remove <path>

# Prune stale references left by directories deleted by hand
git worktree prune

# Move a worktree to a different path
git worktree move <path> <new-path>

What doesn’t come with a new worktree

Only tracked files get checked out. Anything git ignores stays behind: node_modules, .env, build output, virtualenvs, caches. A fresh worktree usually won’t run until you set it up:

cd ../my-app-feature
npm install
cp ../my-app/.env .

“Module not found” in a brand-new worktree is almost always this.

Practical workflow

Step 1: Create a worktree per task

git worktree add ../my-app-auth -b feature/auth
git worktree add ../my-app-tests -b feature/tests

Step 2: Work in each one

Open a terminal per worktree. From there it behaves like any ordinary checkout: install, build, test, and commit as normal. If you’re driving coding agents, this is where you start one in each directory.

# Terminal 1
cd ../my-app-auth && claude "add user authentication"

# Terminal 2
cd ../my-app-tests && claude "write test suite for payments"

Step 3: Merge results

When a branch is ready, merge it back:

cd ~/projects/my-app
git merge feature/auth
git merge feature/tests

Or, if you’re using a tool like crystl, you can merge straight from the UI. Open the Isolation panel in the shard bar and choose Merge to main. It rebases, merges, and cleans up in one step.

Step 4: Clean up

git worktree remove ../my-app-auth
git worktree remove ../my-app-tests

Limitations

You can’t check out the same branch in two worktrees. Each worktree needs its own branch.
Large repos take more disk space. Each worktree is a full copy of the working directory (though they share git objects, so it’s less than a full clone).
You need to manage the worktree lifecycle. Creating, merging, and removing worktrees adds overhead to your workflow.

Running parallel AI agents in worktrees

Worktrees got a lot more popular once people started running coding agents. Agents like Claude Code and Codex read and edit files in whatever directory they’re started in, so two sessions pointed at the same directory overwrite each other’s work. A worktree per agent removes the collision entirely:

# Session 1: Add authentication
git worktree add ../my-app-auth feature/auth
cd ../my-app-auth
claude "add JWT authentication to the API"

# Session 2: Write tests (in original directory)
cd ~/projects/my-app
claude "write integration tests for the payment flow"

Both agents work at full speed without blocking each other.

That’s the short version. For the agent-specific workflow, including the --worktree flag, whether subagents get their own worktree, and the gotchas that only show up when agents are driving, see how to use git worktrees with Claude Code and parallel sessions.

Automating worktrees

The create-merge-cleanup cycle gets repetitive when you’re doing this multiple times a day. crystl automates the entire process with isolated shards:

Create: Click Isolation ▾ in the shard bar and choose New Isolated Shard to create a worktree-backed session
Work: Each shard has its own working copy, so live edits do not overwrite one another
Merge: Open the Isolation panel and choose Merge to main. crystl rebases, fast-forward merges, and cleans up in one step. Or close the shard and choose Merge to Main from the prompt.
Reopen: Orphaned branches appear in the Isolation panel for one-click reattachment
Warnings: If multiple shards are editing database schemas or migrations, crystl warns you before merging so you avoid migration conflicts

You get the benefits of worktree-based isolation without managing the git commands. Each isolated shard is visually distinct in crystl’s interface, so you can see at a glance which sessions are isolated and which branch they’re on.

From isolation to orchestration

Worktrees are the foundation. They let parallel agents keep ordinary in-repo edits in separate working directories. The next layer up is having something drive those agents for you. crystl’s Fanout takes a list of tasks, spins up a worker in its own isolated worktree for each, looks after their approvals and questions, and merges every branch back when it’s done. You talk to one manager instead of babysitting each worktree yourself. A Quest party does the same with role-assigned agents talking in a shared chat. That’s how you keep a whole team of agents busy for hours. See how to run AI coding agents for longer.

When to use worktrees vs. branches

Use regular branches when you’re working on one thing at a time and switching between tasks sequentially. Switching in place is faster and there’s nothing to clean up.

Use worktrees when two things need to be checked out at once: a hotfix on main while a feature branch stays untouched, a long build running on one branch while you write on another, a branch you want to review without disturbing your own work, or two agents on the same repo. The moment stashing and switching starts costing you more than a second directory would, that’s the signal.