Git worktrees–A first step towards a multi-agent development workflow

As AI coding assistants become more sophisticated, we're approaching a future where multiple agents might work on different parts of your codebase simultaneously. But there's a challenge: how do you let multiple processes work on the same repository without constantly stepping on each other's toes?

One solution is to have agents work on dedicated machines like GitHub Copilot Agent does in a GitHub Codespace. But what if you want to have multiple agents working on your local machine?

Enter git worktrees – a powerful Git feature that's been hiding in plain sight since 2015, and the perfect foundation for multi-agent development workflows.

What are Git worktrees?

Git worktrees allow you to check out multiple branches from the same repository simultaneously, each in its own directory. Think of it as having multiple working directories all sharing the same Git history, but each can be on a different branch.

Here's the key insight: while the working directories are separate, they all share the same .git directory.

This means:

• No duplication of Git history
• Minimal disk space overhead
• Lightning-fast branch creation
• Perfect isolation between workspaces

Enter multi-agent development

When you have multiple AI agents working on your codebase:

• Agent A might be refactoring the authentication system
• Agent B could be writing tests for the API layer
• Agent C might be experimenting with a new UI component

With worktrees, each agent gets its own isolated workspace. They can run builds, execute tests, and make changes without interfering with each other – all while sharing the same underlying repository.

Important is to use a good directory and naming structure. Here's one way to do it:

~/projects/
├── my-app/                 # Main worktree (main branch)
├── my-app-agent-1/         # Agent 1's workspace
├── my-app-agent-2/         # Agent 2's workspace
└── my-app-hotfix/          # Quick hotfix workspace

Getting started

Let's say you're working on the main branch and need a separate workspace:

# Create a new worktree for a feature branch
git worktree add ../my-repo-feature feature/new-auth

# Create a worktree with a new branch
git worktree add -b feature/api-refactor ../my-repo-api

This creates a new directory at ../my-repo-feature with the feature/new-auth branch checked out.

You can see the list of created worktrees:

git worktree list

Output:

/home/user/projects/my-repo         abc123d [main]
/home/user/projects/my-repo-feature def456e [feature/new-auth]
/home/user/projects/my-repo-api     ghi789f [feature/api-refactor]

When you're done with a worktree:

# Remove the worktree
git worktree remove ../my-repo-feature

# Or if you've already deleted the directory
git worktree prune

Using worktrees in VS Code

VS Code recently added support for git worktrees., You can create a new worktree directly from the UI:

And of course, also delete it, when you no longer need it:

 

Remark: Although Visual Studio does not have native support for Git worktrees, you can use this feature through the Git WorkTree extension available on the Visual Studio Marketplace.

More information

Git - git-worktree Documentation

Git WorkTree - Visual Studio Marketplace