#cursor#worktree#best-of-n#worktrees.json#automation

Cursor Worktree avancé : Best-of-N et worktrees.json

5 min read

Le billet précédent 08-worktree-merge couvrait le worktree automatique de Cursor et l’Apply. Celui-ci va plus loin sur deux points : Best-of-N (même prompt, plusieurs modèles en parallèle, puis vous en choisissez un à Apply) et worktrees.json (installer les deps, lancer les migrations, copier .env à la création d’un worktree).

Best-of-N : un prompt, plusieurs modèles à la fois

Best-of-N signifie : vous envoyez une tâche, Cursor lance plusieurs modèles dans des worktrees séparés et vous obtenez plusieurs « cartes », chacune avec les changements d’un modèle — choisissez-en une et faites Apply.

Quand utiliser Best-of-N ?

Situation Pourquoi ça aide
Pas sûr du modèle qui convient le mieux à votre codebase Lancez une fois, comparez les sorties, petit benchmark
Problème difficile, un seul modèle peut rater des edge cases Modèles différents, approches différentes, plus de couverture
Comparer la qualité du code Même requête, style et structure différents côte à côte
Tâche difficile, vous voulez plus de succès « du premier coup » Plusieurs modèles essaient une fois chacun, Apply le meilleur

En bref : plusieurs modèles font la même tâche, vous en choisissez un — surtout pour les tâches difficiles ou quand la qualité compte.

Comment l’utiliser

Dans Cursor, au démarrage d’un Agent, choisissez « plusieurs modèles » ou l’option Best-of-N (selon l’UI actuelle). Après l’envoi du prompt vous verrez plusieurs cartes ; naviguez entre elles pour comparer puis Apply celle que vous voulez sur main.

Si vous appliquez plus d’une carte du même run Best-of-N (ex. Apply A puis B), Cursor peut demander : merge avec résolution de conflits ou Full Overwrite (remplacer tout le fichier).

worktrees.json : préparer l’environnement à la création d’un worktree

Quand Cursor crée un worktree, il copie par défaut les fichiers suivis du répertoire principal mais n’installe pas les deps, ne copie pas .env ni n’exécute les migrations DB.
Avec .cursor/worktrees.json vous pouvez indiquer des commandes à exécuter après chaque nouveau worktree, ex. npm ci, cp .env, npm run db:migrate.

Où se trouve la config ?

Cursor cherche dans l’ordre :

  1. Racine du projet : .cursor/worktrees.json
  2. Chemin du worktree

En général on la met à la racine du projet : .cursor/worktrees.json.

Trois clés de config

Clé Description
setup-worktree Générique ; utilisé sur tous les OS si aucune clé spécifique n’est définie
setup-worktree-windows Windows uniquement ; remplace setup-worktree
setup-worktree-unix macOS / Linux uniquement ; remplace setup-worktree

Chaque clé peut être :

  • String : chemin vers un script (relatif au répertoire contenant .cursor/worktrees.json)
  • Array : liste de commandes shell, exécutées dans l’ordre

Exemple : projet Node

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

$ROOT_WORKTREE_PATH est fourni par Cursor et pointe vers le répertoire de travail principal, ex. pour copier .env.
Sous Windows il peut falloir copy ou PowerShell ; vous pouvez séparer par OS :

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

Exemple : exécuter les migrations DB

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

Plus complexe : utiliser des scripts

Pour beaucoup de commandes ou de logique, utilisez un script et référencez-le dans worktrees.json :

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

Placez les scripts sous .cursor/, ex. .cursor/setup-worktree-unix.sh, avec npm ci, copie de .env, chmod, migrations, etc.
Sous Windows utilisez .ps1 et dans le script $env:ROOT_WORKTREE_PATH pour le chemin du répertoire principal.

Astuce : évitez de symlinker les deps dans le worktree — ça peut entrer en conflit avec le worktree principal ; utilisez npm ci, pnpm, bun, uv, etc. pour une installation fraîche.

Nettoyage et limites des worktrees

Cursor gère le nombre de worktrees pour ne pas saturer le disque :

  • Chaque workspace a un nombre max de worktrees (ex. 20)
  • Au-delà, les moins récemment utilisés sont supprimés
  • Le nettoyage est par workspace ; les repos différents ne s’impactent pas

Pour ajuster (si votre version de Cursor le permet), cherchez des paramètres du type :

  • cursor.worktreeMaxCount : nombre max de worktrees à garder
  • cursor.worktreeCleanupIntervalHours : fréquence du nettoyage

Les noms exacts dépendent de la config actuelle de Cursor.

Déboguer le setup worktree

Si après création d’un worktree les deps ne sont pas installés ou les migrations pas exécutées, ouvrez le panneau Output de Cursor, choisissez « Worktrees Setup » dans la liste et consultez les commandes et erreurs exécutées à la création — utile pour déboguer worktrees.json ou les scripts.

Résumé

  • Best-of-N : Même prompt, plusieurs modèles en parallèle dans des worktrees séparés ; comparez et Apply une carte ; utile pour benchmark, tâches difficiles et qualité
  • worktrees.json : Dans .cursor/worktrees.json utilisez setup-worktree / setup-worktree-windows / setup-worktree-unix pour exécuter des commandes ou scripts après création
  • Utilisez $ROOT_WORKTREE_PATH (Unix) ou %ROOT_WORKTREE_PATH% / $env:ROOT_WORKTREE_PATH (Windows) pour copier .env etc. depuis main
  • Les worktrees ont une limite et un nettoyage auto ; débogage via Output → Worktrees Setup

Suivant : 10-headless-scripts — Mode headless avec --print, --force et scripts qui modifient vraiment les fichiers.