Back

Git worktrees are the first line of isolation for coding agents

Not perfect isolation. Not security isolation. Just the easiest way to stop agent work from colliding with your main repo.

And that has quietly become one of the most important things you can do.

Most of us no longer work alone in a codebase. The real workflow now looks like this:

  • you code
  • an agent codes
  • maybe another agent explores or refactors
  • all of it touches the same repository

If all of that happens in one folder, things get messy fast. Lockfiles change, temp files appear, half-finished edits pile up, and after an hour you can't tell what came from you and what came from the agent. I've lost real time to this — staring at a diff trying to reconstruct which changes were mine.

Git worktrees are a very practical answer to that problem. They're not the whole isolation story, but they're a good first boundary, and most people haven't set one up yet.

What a worktree actually is

The simplest way to think about it:

  • a branch is a line of work
  • a worktree is the actual folder where that line of work lives

Most people use one repo folder and keep switching branches inside it. That works, until it doesn't. As soon as you have parallel work, urgent fixes, experiments, or agents touching code, one folder becomes a bottleneck.

Worktrees let you keep multiple working directories attached to the same Git repository.

So instead of:

  • one repo folder
  • constant branch switching
  • constant context switching
  • shared mess

you get:

  • repo/ for your main work
  • repo/.worktrees/agent-auth/ for an agent task
  • repo/.worktrees/hotfix-login/ for a bugfix
  • repo/.worktrees/experiment-cache/ for a temporary test

Same repo, same history, separate working directories. That's the whole idea.

Why this matters for agents

Agents are useful because they move fast. That's also why they create mess fast.

An agent can edit many files quickly, make broad changes, install dependencies, touch lockfiles, generate temporary files, and leave behind work that is directionally interesting but not ready. None of that means agents are bad — it just means they need boundaries.

The easiest boundary you can create is this: give the agent its own worktree. Its branch, uncommitted changes, and folder all live somewhere else, and your main workspace stays readable while it works.

This isolates the work itself. Not the machine, not the runtime, not the process — just the work. And it turns out that's usually enough for day-to-day use.

What they isolate, and what they don't

This distinction matters.

A Git worktree gives you a separate checked-out branch, a separate working directory, separate uncommitted file changes, and better task-level separation.

A Git worktree does not give you VM isolation, container isolation, secret isolation, process isolation, network isolation, or any real security boundary.

If your concern is strong sandboxing, worktrees aren't enough by themselves. But that doesn't make them weak — it makes them honest. They are lightweight repo-state isolation, and for a lot of day-to-day agent workflows, that's already a big improvement.

The practical workflow

The simplest useful pattern:

cd repo
mkdir -p .worktrees
git worktree add .worktrees/agent-checkout -b agent/checkout

Now you have your main workspace in repo/ and the agent workspace in repo/.worktrees/agent-checkout/.

The agent works there. You stay here.

That single decision removes a surprising amount of chaos. When the agent is done, you review the branch like normal. If the work is good, merge it. If it's messy, throw it away. Disposable workspaces make agents much easier to trust, because the cost of being wrong is zero.

The commands that matter most

You don't need to memorize much.

Create a new worktree with a new branch (the one you'll use most):

git worktree add .worktrees/agent-auth -b agent/auth

Create a worktree for an existing branch:

git worktree add .worktrees/feature-billing feature/billing

Create a temporary experimental worktree:

git worktree add -d .worktrees/tmp-test

See all worktrees:

git worktree list

Remove a worktree when done:

git worktree remove .worktrees/tmp-test

Clean stale metadata (if a worktree folder was deleted manually):

git worktree prune

Real scenarios

Isolating agent work. You want an agent working on authentication without touching your main folder:

git worktree add .worktrees/agent-auth -b agent/auth

Point the agent there. Let it work. Review later.

Handling a hotfix without breaking flow. You're halfway through a feature and a production bug appears:

git worktree add .worktrees/hotfix-login -b hotfix/login
cd .worktrees/hotfix-login

Fix the bug in a clean workspace. Your feature work stays untouched.

Running multiple agent tasks in parallel:

git worktree add .worktrees/agent-seo -b agent/seo
git worktree add .worktrees/agent-billing -b agent/billing
git worktree add .worktrees/agent-docs -b agent/docs

Each task gets its own folder and its own branch, which is much cleaner than letting three tasks collide in one checkout.

Why not just clone the repo again?

You can. People do.

But worktrees are a better default. They're lighter, native to Git, and fit task-level workflow better. You're not creating random duplicate copies just to keep work apart — you're using a built-in Git concept designed for parallel working trees. For agent workflows, that makes a lot of sense.

Caveats worth remembering

A branch cannot normally be checked out in two worktrees at the same time. That's Git protecting you from confusion.

Remove worktrees through Git (git worktree remove) instead of deleting the folder manually, or you'll end up with stale metadata that git worktree prune has to clean up later.

And the big one worth repeating once: worktrees are not a security sandbox. They're a workspace boundary. If you need stronger separation, you layer more on top — containers, VMs, remote environments, permission controls. But most people don't even have the workspace boundary yet, and that's the one worth putting in place first.

If you use coding agents and they still work directly inside your main repo folder, you're probably accepting unnecessary mess.

A worktree isn't perfect isolation, but perfection isn't the point. The point is a cheap, fast, native boundary between your work, agent work, experimental work, and urgent work. They're simple enough that more people should use them, and useful enough that they'll become a default part of agent workflows.