Using Git Worktrees for Multi-Feature Development with AI Agents

If you’ve ever needed to work on multiple features simultaneously, you’ve likely encountered the friction of context switching between git branches. The traditional approach—stashing changes, switching branches, and checking out different code—disrupts your flow and can be error-prone. Git worktrees offer an elegant solution, and they become even more powerful when you’re working with local AI coding agents.

What Are Git Worktrees?

Git worktrees allow you to check out multiple branches of the same repository simultaneously in different directories. Rather than having a single working directory that switches between branches, you can have multiple working directories, each on its own branch, all linked to the same .git directory.

Personally, I prefer to keep all of my worktrees under a .trees directory in the root of my project. This helps keep the project contained, and to add a single entry (.trees) to my .gitignore.

How Git Worktrees Work

When you create a worktree, Git:

1. Creates a new directory for the working tree
2. Checks out the specified branch in that directory
3. Links it back to the main repository’s .git directory
4. Maintains shared references, objects, and configuration

This means:

• All worktrees share the same git history and objects (no duplication of .git data)
• Each worktree can be on a different branch
• Changes in one worktree don’t affect others (until you merge)
• You only need to fetch once to update all worktrees

Most importantly for our use case, new worktree instances can be created instantaneously without the agent needing to work outside of our project directory.

Basic Commands for Managing Worktrees

Creating a Worktree

To create a new worktree from an existing branch:

git worktree add .trees/feature-x feature-x

To create a new worktree and a new branch simultaneously:

git worktree add -b feature-y .trees/feature-y main

This creates a new branch feature-y based on main and checks it out in .trees/feature-y.

Listing Worktrees

See all your active worktrees:

git worktree list

This shows you the path, HEAD commit, and branch for each worktree.

Removing a Worktree

When you’re done with a worktree:

git worktree remove ../myrepo-feature-x

Alternatively, you can manually remove the tree, and then clean up the reference files explicitly. This can be helpful if you’re running worktrees in a way where the underlying storage could get pruned, and you need to clean up the reference files separately.

# First, delete the directory (or let git do it)
rm -rf .trees/feature-x

# Then clean up git's references
git worktree prune

Moving a Worktree

It is also possible to move a worktree (git worktree move <src> <dest>), however I have never come across a situation where that was necessary.

Why Worktrees Shine with AI Coding Agents

Local AI coding agents (including Claude Code, Aider, Cursor, Cline, Roo, etc) are drastically changing both how engineers write code, and how many tasks an engineer may have in progress at a time. This can introduce unique workflow challenges that worktrees elegantly solve:

1. Parallel Development Without Context Pollution

When an AI agent is working on one feature, you don’t want it accidentally referencing or modifying files from another feature branch. Worktrees provide complete isolation:

# Terminal 1: AI agent working on authentication feature
cd .tree/feature-oauth
claude-code "implement OAuth 2.0 flow"

# Terminal 2: You working on UI improvements
cd .tree/feature-ui-improvement
# Your changes don't interfere with the AI's work

2. Easy Context Switching for Code Review

Code review will become a larger part of the responsibilities of engineers. With worktrees, you can:

1. Keep an AI agent running in one worktree
2. Checkout a separate branch in another worktree to review changes (or a teammate’s PR)
3. Review and/or test changes without stopping the AI’s work
4. Quickly switch back to provide feedback

3. Avoiding Agent Confusion

Some AI agents maintain context about the current working directory and file state. Switching branches in a single worktree can confuse the agent’s understanding of the codebase state. Multiple agents attempting unrelated tasks in the same repository Worktrees keep each context clean and separate, allowing you (or a separate agent) to handle any conflicts at merge time.

4. Safe Experimentation

Want to let an AI agent try a risky refactoring? Set it up in its own worktree:

git worktree add -b risky-refactor .trees/risky-refactor main
cd .trees/risky-refactor
# Let the AI go wild here without affecting your main work

If it works, great! Merge it. If not, just remove the worktree.

5. Multiple Agents, Multiple Features

With worktrees, you could theoretically run multiple AI agents simultaneously:

# Agent 1: Documentation
cd .trees/write-docs && aider

# Agent 2: Testing
cd .trees/write-tests && cursor

# Agent 3: Refactoring
cd .trees/refactor-frontend && claude-code

Each agent works in isolation, on its own branch, without stepping on each other’s toes.

Configuring AI Agents to Use Worktrees Safely

When directing AI agents to work with worktrees, clear communication is key. Here’s how to set them up for success:

1. Establish Worktree Boundaries

Before starting work with an AI agent, explicitly state the working directory:

I've set up a worktree at `{git rev-parse --show-toplevel}/.trees/{git branch --show-current}` for the current work.
Please work only within this directory and avoid any operations that would affect other worktrees or the main repository.

I have also experimented (with slightly less consistent results) allowing Claude to create it’s own worktrees when given a task.

# Claude.md

- All development should be done in a git worktree.
- A new worktree should be created under a `.trees/{TASK_ID}` directory in the git root. The root directory can be obtained with the `git rev-parse --show-toplevel` command.
- The worktree should use a branch named after the task assigned. A new branch can be created when adding a worktree with `-B <branch>`

There are many additional steps that could be taken to further limit the agent to act only within the assigned worktree, but those are outside the scope of this post.

2. Specify Safe Git Operations

Be explicit about which git operations are safe:

You can safely:
- Create commits in this worktree
- Create local branches
- Pull/fetch from remote
- Push this branch to remote

Do NOT:
- Delete worktrees
- Modify any branches except the checked out branch
- Force push without explicit permission
- Run git operations that affect repository-wide settings

3. Use Configuration Guards

For tools that support configuration files (like Claude Code), you can create a .claude directory in each worktree with specific instructions:

# .claude/rules.md
This is the authentication-feature worktree.

- Work only on files in this directory
- Do not reference or modify files outside this worktree
- Branch name: auth-feature
- Safe to push to origin/auth-feature

4. Establish Clear Communication Patterns

When working with an AI agent across multiple worktrees:

• Always state which worktree you’re referring to
• Use absolute paths when discussing files
• Be explicit about which branch/worktree context you’re in

Example:

In the ~/myproject-auth-feature worktree, please review the changes
to src/auth/oauth.py and suggest improvements. Do not make any changes
to the user interface files, as those are being worked on separately
in the ~/myproject-ui worktree.

Conclusion

Git worktrees transform how you manage parallel development, and they’re particularly powerful when working with AI coding agents. By providing isolated, persistent working directories for each branch, worktrees eliminate the friction of context switching while giving AI agents clear, bounded workspaces. Particularly when starting to run parallel agents, worktrees are a fantastic alternative to a naive branching approach.

Questions or thoughts on using worktrees with AI agents? I’d love to hear about your experiences. Reach out on twitter @nrmitchi or shoot me an email.