Cursor Built-in Worktree: Advanced Usage

06-cursor-cli-with-worktree covers manual worktree + CLI in parallel; this post focuses on advanced use of Cursor’s auto-created worktrees (parallel Agent / Apply): how to queue multiple tasks, whether to merge or overwrite on Apply, how to resolve conflicts, and using git worktree list for day-to-day management. We skip intro concepts and go straight to practice.

Advanced scenario 1: Multiple tasks in parallel, review then Apply

One feature can be split into several “sub-tasks,” each run by an Agent in its own worktree; you only Apply the ones you want, not all at once.

Example: You want to do “refactor utils,” “add unit tests,” and “generate API docs” at the same time:

• Start three parallel Agents (or start them one by one, each in a worktree) with different prompts
• When done you have three outcomes: maybe “refactor” is great, “tests” need tweaks, “docs” you discard
• Apply only the “refactor” card; leave the others un-applied so only the refactor is merged into main—the other two never touch the main directory

Advanced point: You don’t have to commit everything in one go; you can “Apply by task, Apply by card,” and main only gets what you’ve accepted.

Advanced scenario 2: Merge or Full Overwrite on Apply?

On Apply, Cursor tries to merge cleanly. If the same Best-of-N or multiple Applies cause conflicts, it will ask:

In practice: single task, single Agent, few files → merge usually works. Same request run with multiple models (Best-of-N), and you Apply part from card A and part from card B → conflicts are likely; then either Apply only one card, or use merge and resolve file by file. Avoid using Full Overwrite on the same set of files from multiple cards—they’ll overwrite each other.

Advanced scenario 3: Behavior when main has uncommitted changes

When creating a worktree, Cursor brings tracked changes and new files from the main directory into the worktree (Git-ignored files are not). So:

• Change something on main and don’t commit, then start a worktree Agent → the Agent works on top of your “current state”; when you Apply back, you’re merging “your uncommitted changes + Agent changes”
• If you want parallel tasks to start from a clean main, run git stash or commit first, then create the worktree, so you don’t mix “WIP + Agent changes” and get more conflicts on Apply

You can use this the other way: intentionally leave some WIP on main, create a worktree for experimental changes, then use merge on Apply to bring in only the parts you like; leave the rest in the worktree and don’t Apply.

Advanced scenario 4: Inspect and clean with git worktree list

Cursor-created worktrees show up in git worktree list; paths are usually under .cursor/worktrees/<repo>/<id>:

git worktree list

Good habits:

• After Apply and once main looks good, Cursor manages count automatically; if the list has many worktrees and disk is tight, check Cursor settings (e.g. cursor.worktreeMaxCount, cleanup interval) or close unused Cursor project windows so old worktrees get cleaned
• When debugging: the list shows how many “sandboxes” exist and which branch each is on, so you don’t mix up main vs Agent worktrees

Avoid manually running git worktree remove on Cursor-created paths unless you’re sure that Agent is done; otherwise Cursor’s internal state can get out of sync.

Advanced scenario 5: When parallel Agents touch the same files

If you run two Agents, one changing src/auth/ and one src/api/, they usually don’t conflict—Apply one then the other (order doesn’t matter much; merge often resolves automatically).

If both Agents modify the same file (e.g. both change package.json or the same config.ts):

• Apply the first → main has those changes
• Apply the second → you enter the merge flow and may see conflicts
• Use Cursor’s conflict UI to choose “keep this part from main, this part from worktree,” or if you want the second worktree’s version entirely, use Full Overwrite

Strategy: When planning parallel tasks, try to keep file sets non-overlapping per Agent (e.g. one frontend dir, one backend dir); then you rarely need to resolve conflicts by hand.

Summary

• Multiple tasks in parallel: Split into worktree sub-tasks, review, then Apply only the cards you want; main only gets what you accept
• Apply choice: Use Merge to keep some main content; use Full Overwrite when the worktree file should win; avoid repeated Full Overwrite on the same files from multiple cards
• Main directory state: Uncommitted changes are brought into the worktree; for a clean baseline, stash/commit first; or leave WIP on purpose for “experiment worktree + selective merge”
• Management: Use git worktree list to inspect and align with Cursor’s cleanup; keep per-task file sets non-overlapping to reduce conflicts

Next: 09-worktree-advanced — Best-of-N multi-model comparison, worktrees.json config, and cleanup.