CursorRefactoringLevel 3: Workflows

How Do You Try a Risky Refactor Without Touching Your Checkout?

Start the task with /worktree in the Agent input. Cursor runs the rest of that chat in a separate Git checkout, so experimental edits, installs and test runs stay away from your current branch. Use /apply-worktree to bring the result back, or /delete-worktree to throw it away.

Prompt to copy
/worktree [describe the refactor, for example: move the billing logic out of OrderService into its own module]

Don't change behavior. Run [test command] and [type check command] when done, and tell me what passed.

To compare models on the same task:
/best-of-n sonnet,gpt,composer [the same task]
  1. 1/worktree task
  2. 2Agent works in a copy
  3. 3Review the result
  4. 4/apply-worktree or /delete-worktree
The IDE commands from Cursor's Worktrees docs. Your main checkout stays as it was until you apply.

Try it now

  1. 1In the Agent input, type /worktree followed by a small refactor you'd like to try.
  2. 2When it finishes, run git worktree list in a terminal to see the extra checkout, and confirm your main branch's files haven't changed.
  3. 3Type /apply-worktree to bring the changes in, or /delete-worktree to discard them. It worked if your main checkout changed only when you asked it to.

Use it when

A change that might not work out: a framework upgrade, a big module split, a new approach to something central. Use /best-of-n when you honestly don't know which model or approach will do best.

Skip it when

Small changes, since the setup and installs take longer than the edit. It's also unavailable for multi-root workspaces, where Cursor's docs say features relying on a single Git root, like worktrees, are disabled.

Why it works

A Git worktree is a second working folder on the same repository, with its own files and dependencies. Cursor's docs recommend it for risky refactors because cleanup is simple, and you can keep working in your main checkout in the meantime. The agent can run installs, builds and tests without disturbing your branch. You can also commit and push straight from the worktree, without applying it back at all.

Example

Say you want to know whether a test runner upgrade is painless. You run /worktree upgrade the test runner and fix any broken snapshots and keep working on a feature in your main checkout. An hour later the upgrade is done, with tests passing. You ask "Commit and push these changes, then open a PR", and never apply it locally. If it had gone badly, /delete-worktree would remove all trace of it.

Going further

A new worktree doesn't have your ignored files, so add setup to .cursor/worktrees.json, using setup-worktree with commands such as npm ci and cp $ROOT_WORKTREE_PATH/.env .env. Debug it in the Output panel under Worktrees Setup. Cursor doesn't recommend symlinking dependencies. One trap to know: Cursor cleans up older worktrees, keeping at most 25 per machine by default across all workspaces, and that includes worktrees created by git worktree add. Change it with cursor.worktreeMaxCount. Don't leave valuable uncommitted work in an old worktree.

Common mistakes

  • Assuming /best-of-n merges the winner. It only compares runs, so you still pick one and apply it.
  • Forgetting .env, then watching the agent fail on missing configuration.
  • Leaving uncommitted work in a worktree that Cursor's cleanup can later remove.
  • Expecting the Agents Window's worktree interface in the editor. Cursor's docs say the IDE uses these commands instead.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course