Cursor Worktree Advanced: Best-of-N and worktrees.json

The previous post 08-worktree-merge covered Cursor’s automatic worktree and Apply. This one goes further on two things: Best-of-N (same prompt, multiple models in parallel, then pick one to Apply) and worktrees.json (auto install deps, run migrations, copy .env when a worktree is created).

Best-of-N: One prompt, multiple models at once

Best-of-N means: you send one task, Cursor runs multiple models in separate worktrees, and you get multiple “cards,” each with one model’s changes—choose one and hit Apply.

When to use Best-of-N?

In short: multiple models do the same task, you pick one—especially for hard tasks or when you care about quality.

How to use it

In Cursor, when starting an Agent, choose “multiple models” or the Best-of-N option (per current UI). After sending the prompt you’ll see multiple cards; switch between them to compare, then Apply the one you want onto main.

If you Apply more than one card from the same Best-of-N run (e.g. Apply A then B), Cursor may ask: merge with conflict resolution, or Full Overwrite (replace whole file).

worktrees.json: Prepare the environment when a worktree is created

When Cursor creates a worktree, it copies tracked files from the main directory by default, but doesn’t install deps, copy .env, or run DB migrations.
With .cursor/worktrees.json you can specify commands to run after each new worktree is created, e.g. npm ci, cp .env, npm run db:migrate.

Where does the config live?

Cursor looks in order:

1. Project root: .cursor/worktrees.json
2. Worktree path

Usually put it at project root: .cursor/worktrees.json.

Three config keys

Each key can be:

• String: path to a script (relative to the directory containing .cursor/worktrees.json)
• Array: list of shell commands, run in order

Example: Node project

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

$ROOT_WORKTREE_PATH is provided by Cursor and points to the main working directory, e.g. for copying .env.
On Windows you may need copy or PowerShell; you can split by OS:

{
  "setup-worktree-unix": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ],
  "setup-worktree-windows": [
    "npm ci",
    "copy %ROOT_WORKTREE_PATH%\\.env .env"
  ]
}

Example: Run database migrations

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "npm run db:migrate"
  ]
}

More complex: use script files

For many commands or logic, use a script and reference it in worktrees.json:

{
  "setup-worktree-unix": "setup-worktree-unix.sh",
  "setup-worktree-windows": "setup-worktree-windows.ps1",
  "setup-worktree": ["echo 'Using generic fallback'"]
}

Put scripts under .cursor/, e.g. .cursor/setup-worktree-unix.sh, with npm ci, copy .env, chmod, migrations, etc.
On Windows use .ps1 and in the script use $env:ROOT_WORKTREE_PATH for the main directory path.

Tip: avoid symlinking deps into the worktree—it can clash with the main worktree; use npm ci, pnpm, bun, uv, etc. to install fresh.

Worktree cleanup and limits

Cursor manages worktree count so disk doesn’t blow up:

• Each workspace has a max number of worktrees (e.g. 20)
• When over the limit, the least recently used are removed
• Cleanup is per workspace; different repos don’t affect each other

To tune (if your Cursor version supports it), look for settings like:

• cursor.worktreeMaxCount: max worktrees to keep
• cursor.worktreeCleanupIntervalHours: how often to run cleanup

Exact key names depend on Cursor’s current settings.

Debugging worktree setup

If after creating a worktree deps aren’t installed or migrations didn’t run, open Cursor’s Output panel, choose “Worktrees Setup” in the dropdown, and check the commands and errors run at creation time—helps debug worktrees.json or script issues.

Summary

• Best-of-N: Same prompt, multiple models in parallel in separate worktrees; compare and Apply one card; good for benchmarking, hard tasks, and quality
• worktrees.json: In .cursor/worktrees.json use setup-worktree / setup-worktree-windows / setup-worktree-unix to run commands or scripts after creation
• Use $ROOT_WORKTREE_PATH (Unix) or %ROOT_WORKTREE_PATH% / $env:ROOT_WORKTREE_PATH (Windows) to copy .env etc. from main
• Worktrees have a limit and auto-cleanup; debug via Output → Worktrees Setup

Next: 10-headless-scripts — Headless mode with --print, --force, and scripts that actually change files.