teebe › Guides › Cursor worktrees

Cursor worktrees: run parallel agents without conflicts

How Cursor isolates parallel agents in git worktrees, how to configure the environment, and how to see all of them at once.

When you run more than one Cursor agent at a time, each one needs its own copy of your files so they don't overwrite each other mid-edit. Cursor solves this with git worktrees: every parallel agent gets its own isolated checkout, and your main checkout stays untouched while agents work. This guide covers how that works, how to configure the worktree environment, and how to bring the results back.

How Cursor's parallel agents use worktrees

Cursor's parallel agents run in isolated git checkouts, each with its own files, its own installed dependencies, and its own uncommitted changes. Your main checkout is not touched while an agent runs in its worktree, so you can keep working in it, or launch a second agent in a second worktree, without either stepping on the other's files.

That's the same underlying mechanism Claude Code and Codex use for their own parallel or isolated sessions: a linked git worktree per agent, sharing one .git object store but each with its own working directory. For the git side of that mechanism, see the git worktree cheat sheet and git worktree vs branch.

Set up the worktree environment

Agent worktrees are fresh checkouts, so they need their own setup step for things like installing dependencies. Cursor reads this from a .cursor/worktrees.json file in your project root, with three optional keys:

• setup-worktree, the default setup commands.
• setup-worktree-unix, run on macOS and Linux.
• setup-worktree-windows, run on Windows.

Each key can be an array of shell commands, or a path to a script to run. Inside that setup, the $ROOT_WORKTREE_PATH environment variable points back at your main checkout, which is useful if you need to reference something there. Cursor's docs specifically call out that symlinking dependencies like node_modules from the main checkout is not recommended; installing fresh in each worktree is the supported path.

{
  "setup-worktree-unix": ["npm install"],
  "setup-worktree-windows": ["npm install"]
}

Bring the work back

Because each agent's worktree is a separate checkout, nothing you do in one affects another agent running in a different worktree, and nothing either agent does affects your main checkout until you explicitly bring it back. That's the whole point of the isolation: you can let an agent run for a while, check on it later, and decide then whether its changes are worth keeping.

Once an agent finishes in its worktree, you have two ways to bring the change back:

1. Commit or open a PR directly from the worktree checkout, the same as you would from any other git checkout.
2. Run /apply-worktree to bring the changes into your main checkout, then /delete-worktree to remove the worktree once you're done with it.

Cleanup settings

Cursor cleans up worktrees on its own on a schedule, controlled by two settings:

• cursor.worktreeCleanupIntervalHours, default 6 hours between cleanup passes.
• cursor.worktreeMaxCount, default 25, the cap on how many worktrees Cursor keeps around.

Both are configurable if you want Cursor to hold onto worktrees longer, or cap them tighter. If you regularly run a lot of parallel agents on a big repo, it's worth checking these two settings rather than relying on the defaults, especially if you notice a worktree missing that you expected to still be around.

Cursor CLI and plain git worktrees

If you drive an agent from a terminal instead of the Cursor app, you get the same isolation by hand with plain git:

git worktree add ../repo-task -b task
cd ../repo-task
# run your agent here

That's the same primitive Cursor's parallel agents use under the hood, just without the app managing setup and cleanup for you. See the git worktree cheat sheet for the full command set, and git worktree vs branch if you're deciding when a worktree is worth it over a plain branch switch.

Seeing every agent's worktree at once

Cursor manages the worktrees its own agents create. It gets harder to track once you're also running Claude Code or Codex in other worktrees of the same repo: nothing in any single tool shows you all of them together.

teebe is a native macOS git worktree GUI built for exactly this. It lists every worktree of every repo you add, regardless of which agent or tool created it, badges files the instant they change on disk, lets you peek any diff inline with Space, pins as a small always-on-top window beside your terminal, and opens files in whatever native editor you use. See the full rundown in the comparison of git worktree GUIs for Mac.

Frequently asked questions

Where does Cursor store worktrees?

Cursor's docs do not state a fixed on-disk path for worktrees. Run git worktree list in your repo to see exactly where each one lives.

How do I install dependencies in a Cursor worktree?

Add a .cursor/worktrees.json file with a setup-worktree key (or the platform-specific setup-worktree-unix / setup-worktree-windows keys) listing the commands to run, or a path to a setup script. Don't symlink node_modules from the main checkout.

How do I merge an agent's worktree back into my main checkout?

Commit or open a pull request straight from the worktree checkout, or run /apply-worktree to bring the changes into your main checkout, then /delete-worktree to clean up.

How many worktrees does Cursor keep around?

Up to cursor.worktreeMaxCount (default 25), checked every cursor.worktreeCleanupIntervalHours (default 6 hours). Both settings are configurable.

Free · open source · macOS 14+. Back to teebe.io →