Cursor with Git Worktree

Cursor's AI agents edit files in whatever directory you open. By creating separate git worktrees, you can open multiple Cursor windows on isolated branch checkouts, preventing file conflicts when running agents in parallel. This guide covers the complete setup for using git worktree with Cursor.

Why Use Worktrees with Cursor?

Cursor agents modify files directly in whatever directory is open in the editor. If you open the same project in two Cursor windows and run agents in both, they will edit the same files on disk. This leads to race conditions: one agent saves a file, the other overwrites it moments later, and both lose context about what the file actually contains.

Git worktrees solve this by giving each Cursor window its own directory with its own branch. Both directories share the same git history and objects, so branches created in one are visible in the other, but the working files are completely separate.

Cursor Parallel Agents and Worktrees

Cursor now has built-in parallel agent support that uses git worktrees under the hood. When you run multiple agents in parallel, Cursor automatically creates isolated worktrees so each agent works on its own branch without file conflicts. See the Cursor worktree docs for details.

You can also set up worktrees manually for workflows where you want full control:

Single Directory (Default)

The agent runs in your current project directory. It reads and writes files directly in the same folder you have open. This is the default behavior and works well for single-agent workflows. The downside: you cannot safely run a second agent in the same directory, and your own manual edits may conflict with the agent's changes.

Worktree-Isolated

Each agent runs in a separate git worktree directory with its own checked-out branch and source files. Changes are isolated from your main working directory and from any other agents. This is what Cursor's parallel agents feature does automatically, or you can set it up manually.

Cursor Local vs Worktree: When to Use Which

Choosing between Cursor's local mode and worktree mode depends on how many agents you need and whether you want isolation:

Aspect	Local (Default)	Worktree Mode
Agent count	One agent at a time	Multiple agents in parallel
File isolation	None — agent edits your working directory	Full — each agent has its own directory and branch
Setup	Zero — just open the project	Create worktrees first, then open each in Cursor
Disk space	Minimal	Extra space per worktree (node_modules, build artifacts)
Conflict risk	High if you edit while agent runs	None during work; merge conflicts only at merge time
Best for	Simple, single-task work	Parallel development, multi-feature sprints

Rule of thumb: If you are running one Cursor agent and not editing files yourself at the same time, local mode is fine. As soon as you want parallel agents or want to keep your main checkout clean, switch to worktree mode.

Setting Up Worktrees for Cursor Agents

Before launching Cursor agents in worktrees, create the worktrees from the command line. Each worktree needs its own branch:

Create worktrees for Cursor

# Create worktrees for parallel Cursor agents
git worktree add ../my-project-feat-auth feat/auth
git worktree add ../my-project-fix-perf fix/performance
git worktree add ../my-project-refactor-api refactor/api

# Verify they were created
git worktree list

Each worktree is a full working directory. You can open each one as a separate project in Cursor and run an agent inside it. For details on the git worktree add command, see our git worktree add tutorial.

If your project requires dependencies (like node_modules), install them in each worktree before starting the Cursor agent:

Install dependencies in worktrees

# Install dependencies in each worktree
cd ../my-project-feat-auth && npm install
cd ../my-project-fix-perf && npm install
cd ../my-project-refactor-api && npm install

Multi-Agent Parallel Development

With your worktrees ready, open each one in a separate Cursor window and launch an agent in each. Every agent works in isolation, so you can have one agent building a new feature, another fixing a bug, and a third refactoring code, all at the same time.

Open worktrees in Cursor

# Open each worktree in its own Cursor window
cursor ../my-project-feat-auth
cursor ../my-project-fix-perf
cursor ../my-project-refactor-api

# Each window is an independent workspace
# Agents in each window only see their own branch's files

When all agents finish, you can merge their branches back into your main branch using standard git merge or pull requests. See our parallel agents guide for strategies on merging results from multiple agents.

Managing Multiple Cursor Windows

Running several Cursor windows at once is straightforward, but a few practices help keep things organized:

Use Descriptive Branch Names

Name your worktree branches clearly (e.g., feat/user-dashboard, fix/login-timeout). Cursor shows the project folder name in the title bar, so a descriptive branch name makes it easy to identify each window.

Monitor System Resources

Each Cursor window runs its own language server, extensions, and AI agent process. On machines with limited RAM, keep the number of concurrent windows to two or three. Close windows for completed worktrees to free resources.

Keep a Terminal Window for Git Operations

Use a separate terminal to run git worktree list, manage branches, and merge results. This keeps your git operations centralized rather than scattered across Cursor windows.

Tips and Common Issues

Cursor Settings Are Per-Window

Workspace settings in .vscode/settings.json are tracked by git, so each worktree gets the same settings. However, user-level settings apply globally. If you need different configurations per worktree, use workspace settings.

Extensions in Worktrees

Cursor extensions are installed globally, not per workspace. This means all your worktree windows share the same extensions. If an extension caches data per-project (like ESLint or TypeScript), each worktree window builds its own cache.

Port Conflicts for Dev Servers

If your project starts a dev server, each worktree will try to bind to the same port. Either assign different ports in each worktree or only run the dev server in the worktree you are actively testing.

Cleaning Up

When you are done with a worktree, close the Cursor window first, then remove the worktree from the command line:

Clean up worktrees

# Remove worktrees after merging
git worktree remove ../my-project-feat-auth
git worktree remove ../my-project-fix-perf

# Clean up stale references
git worktree prune

Summary

Cursor works naturally with git worktrees. Create a worktree per task, open each in its own Cursor window, and let agents work in parallel without stepping on each other. The worktree mode gives you full isolation while keeping everything in a single repository. For more on worktree fundamentals, see our what is git worktree guide, or explore other AI tool integrations.