Cursor with Git Worktree

Cursor's AI agents can run in two modes: local (editing files in your current directory) and worktree (editing files in an isolated branch checkout). Understanding the difference and knowing when to use worktrees is key to running multiple Cursor agents without file conflicts. 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.

Local vs Worktree Mode

When Cursor runs an agent, it can operate in two modes:

Local Mode

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 Mode

The agent runs in a separate git worktree directory. It has its own checked-out branch and its own copy of all source files. Changes are isolated from your main working directory and from any other agents running in other worktrees. This is the mode you want for parallel development.

The key difference: in local mode, you and the agent share the same files. In worktree mode, the agent gets its own copy. For parallel agent workflows, always use 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.