Git worktrees give Cursor agents separate checked-out folders, so each can edit its own working copy. They don’t eliminate the need to integrate branches, resolve overlapping changes, and test the combined code. Cursor’s workflow also differs between the Agents Window and the IDE, and its cleanup can include worktrees you created yourself.

Separate checkouts still meet at merge time

A worktree is a separate checkout of a Git repository. It keeps agents from writing to the same working copy, but separate branches can still change the same file or lines. Those changes meet when you integrate the branches.

Git can combine non-overlapping edits. Overlapping edits may require conflict resolution, and even a clean merge can leave a bug in the combined code. For example, Git’s documentation describes how a renamed function can leave a caller using the old name. Review and test the integrated result, not just the merge status. Git’s merge-conflict manual explains the difference.

Treat each worktree as a separate draft: the integration step still needs review and tests.

Cursor’s worktree options depend on where you work

Cursor’s UI-native worktrees are available in the Agents Window. In the IDE, Cursor documents Worktree Skills commands, including /worktree, /best-of-n, /apply-worktree, and /delete-worktree. With /best-of-n, candidate runs use separate worktrees for comparison; Cursor doesn’t merge them automatically, so you choose and apply a result yourself. Cursor’s worktree documentation describes these workflows.

To customize worktree setup, use .cursor/worktrees.json. It supports Unix-specific, Windows-specific, and generic setup keys. You can provide command arrays, which run sequentially, or a script path. Cursor checks for the file in the worktree path first, then the project root.

Cursor cleanup can include manually created worktrees

For Cursor 3.5 and later, Cursor documents a default maximum of 25 worktrees per machine. Its documentation also says manually created worktrees, including those made with git worktree add, are eligible for automatic cleanup. A six-hour cleanup interval is an example setting in the documentation, not a universal interval.

If you rely on a manually created worktree, don’t assume that creating it outside Cursor’s manager exempts it from cleanup. Check the cleanup settings that apply to your setup.

A dated workaround for an interrupted agent task

In a September 10, 2026 forum reply, Cursor staff attributed reports of interrupted agent turns to an agent creating a worktree and switching its root mid-task. Staff suggested starting the agent in the folder where it should work instead; they also said that “continue” resumes a stopped task. The staff reply describes that explanation and workaround.