We started integrating AI coding agents into our day-to-day engineering workflow a few months back. The setup was straightforward — agents running on the same repo as the team, picking up tasks, generating code. It worked until it didn’t.
The problem was branches. An agent would check out a branch to work on a task. A developer on the team would pull the repo, make changes, and push. The agent, still mid-task on a stale state of the same branch, would generate code against a base that no longer existed. We lost a few hours to this before we stopped calling it bad luck and started looking for a fix.
Git worktrees are what we landed on.
What a Worktree Actually Is
Most developers work on one checkout of a repository at a time. When you need to switch context, you stash or commit and then check out a different branch. A git worktree gives you a second checkout — a separate working directory on disk, linked to the same repository, locked to its own branch.
Your agent works in its worktree. You work in yours. Same repo, same history, no collisions.
# Create a worktree for the agent to work in
git worktree add ../my-project-agent-workspace agent/task-refactor-auth
That command creates a new directory at ../my-project-agent-workspace, checked out to a new branch called agent/task-refactor-auth. The agent does its work there. You stay in the main working directory on your branch.
The Setup We Use
We keep a consistent naming convention. Agent worktrees go into a sibling directory with a -agent suffix, and branches follow the agent/ prefix pattern.
# From your main project directory
git worktree add ../my-project-agent agent/$(date +%Y%m%d)-task-name
The date prefix in the branch name keeps things ordered when you have more than one agent task running in parallel. We found that without it, worktree directories pile up with generic names, and it becomes unclear what’s active.
When the agent finishes its task, you review the diff, merge or cherry-pick what you want, and clean up:
git worktree remove ../my-project-agent
git branch -d agent/20260422-task-name
The main repo stays clean. No leftover branches, no orphaned directories.
The Configuration Mistake That Will Cost You a Morning
The mistake we made — and that most teams make — is not isolating dependency directories between the main working directory and the worktree.
If your project has a node_modules, a vendor directory, or compiled assets that live at the project root, both your main checkout and the agent's worktree will reference the same physical directory on disk. An agent that runs a package install, a bundle install, or a build step inside its worktree will modify those shared directories. You will come back to your environment and find your dependencies in an unexpected state.
The fix is to configure your tooling to write dependencies into the worktree’s own directory, not a shared location. For most package managers, this means setting an explicit install path:
# Node — tell npm to install into the worktree's own node_modules
cd ../my-project-agent
npm install --prefix .
# Ruby — tell Bundler to use a local vendor path
bundle install --path vendor/bundle
Alternatively, keep agent tasks to code generation only — no install steps, no build steps. That constraint is often reasonable and avoids the problem entirely.
Cleaning Up After
Worktrees don’t clean themselves up automatically. It is easy to end up with a dozen stale worktree directories after a few weeks of regular agent use. We added a small shell alias to list active worktrees:
alias wt-list="git worktree list"
And a cleanup habit: at the end of each week, run git worktree list, remove anything that's been merged or abandoned, and delete the associated branches.
Ours was not a complicated problem once we understood what was causing it. Agents are just another developer on the codebase. Give them their own desk, and they stay out of the way.
Comments
Loading comments…