Skip to content
Cursor Handbook

Worktrees

One repository, several checkouts, so parallel agents stop overwriting each other.

  • Working with repos
  • Every plan. Requires a git repository.

Checked against cursor.com on 25 September 2026

What it does

A git worktree is a second working directory backed by the same repository, checked out to a different branch. The history is shared; the files on disk are not. That property is what makes it the right primitive for parallel agents.

Without worktrees, two agents editing the same checkout race each other: one stages a file the other is mid-way through rewriting, and the result is a diff neither of them intended. With worktrees, each agent gets an isolated directory, works on its own branch, and you merge the results deliberately.

The practical pattern is one worktree per task rather than per agent. Spin one up for the refactor, another for the bug fix, let both run, then review the two branches as separate pull requests.

Using it

  1. Create a worktree. Cursor can create and manage worktrees from its interface, or use git worktree add ../feature-x -b feature-x from the terminal.
  2. Point an agent at it. Open the worktree directory and start the agent there. It sees only that checkout.
  3. Merge and remove. Review each branch on its own, merge what you want, then remove the worktree so stale checkouts do not pile up.

Checked against Worktrees documentation on 25 September 2026.

Frequently asked questions

How do I run multiple Cursor agents at once?
Give each one its own git worktree. Each worktree is a separate directory checked out to a separate branch but sharing one repository, so agents cannot overwrite each other's files and each result arrives as its own branch.
Do worktrees duplicate the repository on disk?
They duplicate the working files but not the git history, which is shared with the main repository. That makes them much cheaper than a full second clone.
Is this different from cloud agents?
Yes. Worktrees isolate parallel agents on your own machine. Cloud agents run on Cursor's infrastructure, so they are isolated by default and do not touch your local checkout at all.

Keep reading