Git worktrees for parallel agentic development

Most of the new “agentic” tools are good at working in parallel.
Git often is not.

If you, plus one or more agents, are all trying to make changes in the same repository at the same time, a single working directory quickly turns into a mess. Someone forgets to stash. Someone else rebases the branch the agent is on. Now you are debugging Git instead of shipping code.

Git worktrees fix this with one simple idea:

one task = one worktree = one branch = one directory

No cloning, no weird Git plumbing. Just extra working directories that share the same .git history.

The problem: one repo, many tasks, many agents

Imagine this setup:

task A: refactor a module
task B: add logging
task C: investigate a bug

With a classic Git workflow and one directory:

you keep checking out different branches in the same place
tools and agents trip over each other’s changes
local state is often half‑dirty, half‑stashed
it is hard to see what is actually on which branch

When you add agents (for example Cursor agents) into that mix, things break even faster. An agent expects the directory it sees to be its world. When you re‑use that same directory for several tasks, it no longer has a stable view of the codebase.

One task, one worktree, one agent

Git worktrees let you check out multiple branches at once. Each branch lives in its own directory, but they all share the same .git data.

You can think of it as “cheap clones” with a shared history.

Example layout:

repo/
├─ main/        # main branch
├─ feature-a/   # agent A
├─ bugfix-b/    # agent B

Each directory has:

a clean working tree
its own checked‑out branch
an isolated space for one human or one agent

You keep the mental model simple: if you are in feature-a/, you are working on feature-a. Nothing else.

The only git worktree commands you really need

You can do a lot with just four commands.

Create a new worktree

git worktree add ../feature-a -b feature-a

This creates a new directory ../feature-a, checks out a new branch feature-a there, and attaches it to the same .git history as your main repo.

List existing worktrees

git worktree list

Useful when you forget what you have open.

Remove a worktree

git worktree remove ../feature-a

This removes the working directory and detaches it from the list of active worktrees. The branch still exists until you delete it with git branch -d feature-a.

Prune stale metadata

git worktree prune

If a worktree directory was deleted manually, prune cleans up the leftover references.

For most day‑to‑day work, that is the whole API.

A simple workflow with Cursor agents

Here is how you might set this up when using agents inside Cursor.

1. Start from a clean main

git checkout main
git pull

Make sure main is up to date and clean before branching off.

2. Create one worktree per task

git worktree add ../task-auth -b task-auth
git worktree add ../task-logging -b task-logging

Now you have:

../task-auth on branch task-auth
../task-logging on branch task-logging

3. Open each directory separately

open ../task-auth in Cursor → agent A works there
open ../task-logging in Cursor → agent B works there

Each agent sees a clean repo focused on its job.

4. Give agents a clear scope

In each worktree, tell the agent something close to:

You are only working in this directory and branch.
Do not touch other worktrees or assume they exist.

This matches Cursor’s own guidance for parallel work on separate branches and directories. The filesystem boundaries do most of the coordination for you.

Why worktrees fit agentic development

Agent systems work best when:

tasks are truly independent
state does not silently change under them
humans can see what each agent is responsible for

Git worktrees naturally support that:

filesystem isolation – each task has its own directory
branch isolation – history stays clean per task until you merge
controlled integration – you choose when and how work comes back to main

Instead of hoping agents stay out of each other’s way, you give them separate rooms.

Merging back to main

When a task is done:

Go back to your main directory:
```
cd main
git checkout main
git pull
```
Merge the finished branch:
```
git merge task-auth
```

Remove the worktree:

git worktree remove ../task-auth
git branch -d task-auth

Repeat the same pattern for each task branch.

Common pitfalls and how to avoid them

Tools that assume a single repo root
Some scripts or tools expect to run from the original repo directory. Run them from inside the specific worktree instead, or update their paths.

Forgetting which branch you are on
Inside a worktree, git branch --show-current is your friend. Put it in your shell prompt if you often lose track.

Too many active worktrees
Worktrees are cheap, but not free. Close them aggressively once a task is merged. It keeps your mental model small.

When to reach for worktrees

Worktrees make sense when:

tasks are independent
agents (or humans) should run in parallel
context switching between tasks hurts your focus

They are probably overkill when:

you are making small, sequential edits
only one person or agent is touching the repo
you already have a tight trunk‑based workflow

If you rely on agents and you are still juggling everything in one directory, it is worth trying worktrees for a week. Set up one directory per task, one agent per directory, and see how much Git noise disappears.