Cursor 3: Worktrees & Best-of-N

New in Cursor! · Full changelog · Main announcement

We’ve redesigned how you work with worktrees and compare model results for the same task in Cursor.

What’s changed

Worktrees are now driven by two explicit commands: /worktree and /best-of-n. This gives you more control over when work moves into an isolated checkout, and worktree management is fully agentic from there.

/worktree starts an isolated Git checkout for the rest of a chat. Your main branch stays untouched until you apply the result back with /apply-worktree.

/worktree fix the failing auth tests and update the login copy

/best-of-n runs the same task across multiple models at once, each in its own worktree. A parent agent provides commentary on the different results so you can pick the best one, or ask it to merge parts of different implementations into a single commit.

/best-of-n sonnet, gpt, composer fix the flaky logout test

Customize worktree setup for your project with .cursor/worktrees.json, including OS-specific commands for installing dependencies, copying environment files, and running migrations.

Note: If you had agents previously running in worktrees, those chats will still work. You’ll need to use the new commands for new agents.

Learn more: Worktrees documentation

3 Likes

Great progress with the new release.

Is it possible that work trees and beat of n can work in a multi repo workspace. This is my biggest pain point and historically blocking my ability to try these features (similar issue on background agents / automation too).

We have a back end and front end repo that needs to be coordinated together and I know we aren’t alone.

Keen to see this spa e evolve quickly to support this scenario including cloud agents.

2 Likes

Yes, this is now possible! /worktree and /best-of-n now support multi-repo! This is one of the best things about the new implementation.

2 Likes

oh that’s great news - thanks for confirming - looks like it still isn’t availbe via cloud agents (via cursor.com/agents) but good to see some progress on this one.

1 Like

I don’t seem to have /worktree or /best-of-n available, it doesn’t show up as a command or anything. I tried it just in case but it just confused the agent… At the moment it seems like there’s no way for me to run an agent in a worktree from the new agent window. I do actually see those commands in the editor window, though.

Version: 3.0.12 (Universal)
VSCode Version: 1.105.1
Commit: a80ff7dfcaa45d7750f6e30be457261379c29b00
Date: 2026-04-04T00:13:18.452Z (1 day ago)
Layout: glass
Build Type: Stable
Release Track: Default
Electron: 39.8.1
Chromium: 142.0.7444.265
Node.js: 22.22.1
V8: 14.2.231.22-electron.0
OS: Darwin arm64 25.1.0

It’s awful:

  • Massive UX downgrade compared to the previous approach
  • It’s way slower to set up, burns unnecessary tokens (especially great when you’re using Opus 4.6)
  • It’s fragile because sometimes the agent won’t follow the instructions accurately
  • When you’re using sandbox mode you have to come back to the chat multiple times to approve the worktree setup scripts to execute outside the sandbox
  • It pollutes the chat history with worktree setup scripts
  • It’s now harder to distinguish between local chats and worktree chats in the UI
9 Likes

Couldn’t agree more. This is really disappointing, Cursor team.

Implementation brings some new features but overall is a massive regression.

3 Likes

Hey @piercegov

Better support for worktrees in the Agents Window is coming soon! Have you tried out the Worktree setting when configuring a new agent?

I am signing in specifically to voice my disappointment because the previous worktree implementation functioned perfectly. The current version requiring using /worktreeskill is unreliable and fails to work with Plan Mode. Furthermore, it randomly applies changes to the head branch rather than the intended worktree. This regression is a significant step backward in functionality.

8 Likes

I’m also signing in specifically because I have yet to get a single session to successfully use a worktree since Cursor 3, despite trying somewhere >20 times, with various approaches. Worktrees were my primary workflow until the upgrade, because I do a lot of parallel, independent work in the same repository.

I tried both /worktree and the Worktree option you’ve sent a screenshot of in the new Agent Window.

With /worktree (when it’s actually available, which is hit-and-miss), the Agent fails to create the worktree in the sandbox, then either:

  • tries outside the sandbox, which requires manual interaction to allow it to run a bunch of commands, which so far have also not resulted in changes landing in a worktree, OR
  • continues in the non-worktree directory, which imo is worse than just failing, because it creates a mess of changes.

The Worktree option just seems to have no effect. It doesn’t matter whether I select it or not, the session runs in the normal project directory as if I had selected “local” (and that is also what’s shown for the session after submitting the initial prompt).

As a result, I have just downgraded to Cursor 2, so I can actually get some work done.

1 Like

@Ptr_Zjc Thanks for calling this out. We know that /best-of-n isn’t working with Plan mode and I’ve added a comment to our internal ticke that /worktree isn’t working either.

@jeyj0-work If you have the opportunity to file some bug reports with some examples, we’d love to get this working better for you.

(I’m also signing in specifically to share this feedback.)

I’m trying to understand the shift toward agentic worktree management. In Cursor 2, the UI made worktrees straightforward, transparent, and easy to control. That ease-of-use was a major productivity boost for me, especially compared to other agent-driven platforms.

With the new approach, it feels like some of that visibility and control is replaced by abstraction, and I’m not yet seeing a clear benefit. Managing worktrees through agents currently feels more fragile and harder to reason about, which introduces friction into something that used to be simple and reliable.

Personally, I prefer not to manage worktrees through chat. I’d rather configure them quickly and then focus on working with the agent, as before.

Of course this is subjective, but it seems to align with early impressions from other heavy users as well. I’d also be genuinely interested to understand what drove this decision, if you’re open to sharing.

4 Likes

The fact that this update auto-installs, that there is no clear way to downgrade to a previous version (you lose your chat history, and even then it keeps auto-updating), all while ruining some people’s daily workflows is just sickening. I’ve lost all trust in Cursor after this.

2 Likes

Prior to this update, the worktree workflow was in a stable spot (bringing over changes cleanly, undoing changes cleanly, visual representation of being in worktree) and now the UX is muddied and the application of worktrees is not stable. All I want at the core is an easy visualized way to do true parallel work. My previous workflow was to open up an agent, choose worktree mode and then have it do some task. I would come back to it later and apply changes to the main repo and test. If I needed further adjustments, I would undo the applied changes, give it xyz instructions, and come back later and rinse and repeat.

Regarding new update:

I always start out with plan mode. I tried using /worktree skill in plan mode and nothing happened. After the plan was built out, I then told it to build the plan to a worktree with /worktree in agent mode.

It started building out the plan on a worktree, but when I opened the worktree repo itself to inspect it, cursor had not respected my worktree.json at all, which defines copying over dotfiles, running setup, etc. The worktree repo had none of this. As such, the agent failed when trying to do certain task work once it was operating in the context of the worktree, since these post-setup changes were not applied.

After completing some work, I instructed the agent to copy over worktree files and it takes much longer than it used to as it goes through the agent and all subtasks to do this. This also in and of itself consumes tokens. Previously, bringing over changes was handled quickly and simply through an “Apply Changes” button.

Now with the changes applied to the main repo, there is no quick way to unapply the worktree changes. I have to deal with discarding the changes manually or again telling the agent to discard, which takes time and tokens.

There is not an easy way to identify work that exists on a worktree now because it’s buried in chat. Previously, you could identify a worktree agent by the worktree icon. Also, you could click on the agent to get the specific worktree name.

Also, your chat history is now polluted with messages that deal with setup/copy over/discard related things, instead of the chat being focused on the task you are actually trying to accomplish.

In addition, this whole workflow also makes it easy for the agent to lose context of where the changes should happen. I have to explicitly tell the agent to make whatever change I’m suggesting on the worktree for every message, otherwise it was sometimes making its changes in the main repo.

As outlined above, there are many UX frustrations with the new worktree changes.

5 Likes

Moving to a slash command was definitely a step in the right direction, allowing for new automation use cases. However, the way it was implemented is too unreliable. It should be a tool call similar to the SwitchMode tool that deterministically creates and sets up the worktree and changes the workspace.

The skill-based approach is too unreliable because it relies on the agent understanding the instructions and running arbitrary batch scripts.

Strongly agree with the feedback that not having first class software support for worktrees and best-of-n is a UX regression. Every member of my team is disappointed in the cursor 3 release because of this (why remove a feature we rely on?)

This completely breaks workflows where installing & running our product on a worktree isn’t feasible. No longer can we quickly apply to main off a worktree, test it, move it back to the worktree & ask for changes. Instead we have to awkwardly ask the LLM to do it for us.

This makes no sense, and we’re disappointed.

3 Likes

multi-agent for multi UI proposals was something I wanted in Claude, so cool and well implemented as a feature, and I had to use Cursor to have it. Without it, I can definitely leave Cursor, adios.

1 Like

The worktree approach in V3 is not even implemented.

You can kick-off a chat into a worktree with selecting it from the Local/Worktree/Cloud dropdown when starting the chat but the “Chat asscoiated with branch“ feature is still only locked to your main worktree. The changes you see, the PR you see are all associated with the main worktree. You have NO ui indication at all that the agent is in a worktree and the branch name is even misleading you. It’s only when looking at the git state that you actually realize where it’s doing the changes.

Why even add the worktree option when NONE of the features in Glass are usable with it?

For being the home where you “manage your agents“ it’s completely useless for parallel work UNLESS you only work with Local/Cloud. I’m getting the feeling that the Cursor team doesn’t appreciate how much devs just want to use the beefy macbooks they have to actually use worktrees instead of going all-in on expensive cloud compute.

That said, the branch-convo association is the right direction. We want simple 1-to-1 relationships between ticket, branch, convo, PR to have as little mental overhead of what is associated to what. Otherwise any kind of parallelization of work is just making you a scatter-brain.

1 Like

been using Cursor 3 for some days now, the only effect it had is that I now does not work with worktrees anymore. :melting_face:

1 Like