Git Worktrees: The Simplest Way to Parallelize Your Coding Agents

Git worktrees have existed for a while now. They give you the ability to have multiple working directories, all sharing the same git instance. This makes it easier to work on multiple pieces of work at the same time without the code from one interfering with the others. For example, I could work on a bugfix on one worktree, and focus on a feature on my main worktree.

Worktrees make working with multiple coding agents on the same codebase at the same time even easier. I can focus on a larger UI-based task that uses my dev server while setting a handful of agents off to fix some bugs or little improvements. Yesterday I focused on a tricky feature requiring a bunch of thought about the domain model + UI changes while getting four agents to fix some bugs and add some new UI functionality in some of the app’s internal pages. I’ll explain the workflow in a second, but those agents fixing the bugs would commit when they’re done, and I’d quickly check their output and tell them to “open a PR”. One quick glance at the code and it’s merged. This is simplified a bit, but you really can achieve some great throughput in shipping with multitasking these agents.

The best part about worktrees is that it pairs so well with using multiple agents at the same time. The agents won’t accidentally bump into each other since each agent has its own directory to work in. Coding agents are smart enough these days to cd into the worktree and run all of its commands in there too. Doing the regular git operations like committing and opening PRs works as expected within a worktree.

You don’t need to know much about worktrees to use them

The great thing is that you can use worktrees with zero knowledge of what’s happening under the hood. Coding agents are smart enough to call the right git commands to set up a worktree and branch. With a little guidance, agents can consistently create worktrees in the right place using the right commands.

Here’s what I’ve placed in my global CLAUDE.md file (~/.claude/CLAUDE.md) to let the agent know what to do every time it’s asked to use a worktree:

## Git Worktrees

When setting up git worktrees, always use `~/.worktrees/` as the base
directory. Name worktree directories using the pattern
`{repo-name}-{branch-name}`. For example:

`git worktree add ~/.worktrees/my-project-my-feature -b my-feature main`

Then whenever I’m using Claude Code to, say, fix a bug, I can just prompt it in a worktree fix this UI bug in .... It’s that easy. The Claude Code instance can remain in the same main working directory of the project and it’s smart enough to know to cd into that worktree directory for every command or tool it uses.

Don’t expect it to be a silver bullet

There are some obvious limitations that worktrees don’t, and shouldn’t, solve. Depending on the project, if there are external dependencies (e.g. port numbers, databases, external APIs), things like running the dev server, tests, or code that affects anything outside the working directory could cause one agent to trip up another. Keep this in mind when using worktrees.

Being able to isolate instances of your project from each other is the holy grail, as that allows the agent to fully do anything it deems useful to its task at hand. Run a dev server and have the agent use a browser? Sure. Let it go wild refactoring your database tables? Go for it. Git worktrees just handle the filesystem separation. Your own solution is needed for isolation — whether that’s assigning random ports, setting up and tearing down dependent services, or database-level separation. Don’t let this stop you from utilizing agents though! They can still be quite effective at reading and writing the code, running tests, and code linters. The extra flexibility you get from pushing agents to do bigger changes and providing them with ways to check their own work makes them even more powerful at building high-quality code.