Finally caught the Git worktree bus

I’ve been living under a rock.

With a mature tool you’ve been using for years, you settle into an effective way of working and tend to stop paying attention to the small feature additions over time. You don’t skim the changelogs. You don’t explore new subcommands. The tool works, you’ve got a dozen other things to learn, and yak shaving your source control setup isn’t one of them.

That’s how I missed git worktree for over a decade. Then I started working with agentic development tools, and worktrees went from “ooh, that’s cool!” to “how did I ever work without this?”

So what are worktrees? #

A worktree is a second (or third, or fourth, or nth) checked-out working directory from the same repository. Each worktree has its own branch, its own index, and its own working files - but they all share the same .git object store. No duplication, no divergence.

The basic commands are straightforward:

# Create a worktree for a feature branch in a sibling directory
git worktree add ../my-feature feature-branch

# See what worktrees are active
git worktree list

# Clean up when done
git worktree remove ../my-feature

That’s most of what you need. They’re useful any time you want parallel work without shared state - code reviews, spikes, experiments, or just keeping a stable branch checked out while you hack on something else.

But the reason they finally came onto my radar was… AI.

What has this got to do with AI? #

If you’re using an AI coding agent - Claude Code, Cursor, Copilot Workspace, or any of the growing list - you quickly hit a practical issue: the agent needs to modify files. The same files you’re working on. In the same repository.

This leads to a few familiar workarounds. You stash your changes, let the agent work, then pop your stash and resolve conflicts. Or you clone the repo a second time and now you’ve got two copies of everything, with all the confusion that brings.

None of this is catastrophic. But it adds drag to what should be a fluid workflow. And if you’re trying to evaluate whether agentic tools actually make you faster, that friction doesn’t exactly help.

Worktrees solve this cleanly. You work in the main worktree, the agent works in its own. Different directories, different branches, zero interference. What I hadn’t realised is that isolated working directories are an assumption in many newer tools, and worktrees are how Git provides that.

In practice, this looks something like:

~/projects/my-app/           # Your main worktree - you're on 'main' or a dev branch
~/projects/my-app-agent/     # Agent's worktree - checked out on 'agent/feature-x'

The agent can rewrite files, run tests, even break things - and your working directory is untouched. When the agent’s work looks good, you review the branch and merge it like any other PR. If the work is rubbish, you throw the branch away. There’s no stashing, no conflict resolution, no “wait, which version am I looking at?”

Here’s what a typical session looks like end-to-end:

# Set up the agent's worktree
git worktree add -b agent/add-auth ../my-app-agent 

# Point your agent at the new directory and let it work
cd ../my-app-agent
# ... agent does its thing (commits to agent/add-auth)

# Review the result from your main worktree
cd ../my-app
git log --oneline main..agent/add-auth
git diff main..agent/add-auth

# Merge if it looks good
git switch main
git merge agent/add-auth

# or, bin it if it's not
# git worktree remove --force ../my-app-agent
# git branch -D agent/add-auth      # force-delete unmerged branch

# Clean up
git worktree remove ../my-app-agent
git branch -d agent/add-auth

A few things worth knowing #

You can’t check out the same branch in two worktrees. Git enforces this, and it’s a good constraint. If you need to work on the same branch as the agent, one of you needs a different branch. In practice, having the agent work on a dedicated branch is better discipline anyway.

Worktrees are cheap. Because they share the object store, a new worktree is barely more than a checkout. It’s nothing like the cost of a full clone.

Clean up after yourself. git worktree remove is the proper way to dispose of a worktree. If you just delete the directory, the reference lingers - git worktree prune will tidy that up, but it’s better to do it cleanly.

Your IDE might need a nudge. Some editors handle multiple worktrees gracefully; others get confused about which directory they’re watching. If you’re opening the agent’s worktree to review changes, treat it as a separate project.

Dependencies and build artifacts don’t carry over. Each worktree has its own working directory, which means node_modules, virtual environments, build outputs - all of it lives per-worktree. The first time you set up an agent worktree, you’ll need to install dependencies. For some projects, a quick setup script that creates the worktree and runs the install in one step is worth the five minutes it takes to write.

The bigger picture #

As development becomes more parallel and more agent-driven, having isolated working directories stops being a convenience and starts feeling fundamental. A single mutable working directory is a poor fit for a world where humans and agents are exploring multiple threads of work at once. Worktrees have been in Git since 2015 - the tooling was just waiting for the workflow (and me) to catch up.

If you’re experimenting with AI coding agents and you haven’t tried worktrees yet, spend ten minutes setting one up. The workflow improvement is immediate and the overhead is negligible.

All perfectly good reasons to have discovered this years ago. I didn’t. But better late than never.