T3ckfr3ak1/cursor-chrome-linux

Cursor-Chrome

Installation d'abord (si l'utilisateur a demandé d'installer / a déposé le lien GitHub)

Ne pas expliquer et s'arrêter. Exécuter :

• Cloner ouvrir comme espace de travail → npm run install:agent
• URL uniquement (Windows) →
  irm https://raw.githubusercontent.com/T3ckfr3ak1/cursor-chrome-public/main/scripts/remote-bootstrap.ps1 | iex
• Prouver : GET http://127.0.0.1:9222/health → "ok": true

Canonique : dépôt INSTALL.md + AGENTS.md + .cursorrules.

---

Protocole de pilotage (même dossier) : THREAD-PROTOCOL.md
Si cette compétence a été installée via npm run install:agent, le chemin du client se trouve sous la racine d'installation dans src/client.js.

En cas de conflit pour le contrôle du navigateur, THREAD-PROTOCOL.md prévaut.

---

Démarrage rapide (à chaque thread après installation) — OBLIGATOIRE

Liaison : Lisez THREAD-PROTOCOL.md et suivez-le intégralement. Sauter claim, threadId ou release n'est pas autorisé.

1. Santé : GET http://127.0.0.1:9222/health — si hors service, exécutez l'installation ou start-minimized.bat depuis la racine d'installation
2. Revendiquez votre onglet (threadId stable, max 20 onglets globaux)
3. Pilotez via le client ou REST ; ne remontez pas la fenêtre — laissez-la rangée ; l'humain regarde via la barre des tâches / /live
4. Multi-thread : threadId unique par chat Cursor ; ne pilotez que votre tab.id ; les clics humains sur les onglets n'arrêtent pas les autres threads
5. Popups : window.open → onglet enfant avec le même threadId. Utilisez listPopups / resolveOverlay ; ne pilotez jamais le popup d'un autre thread. Les dialogues dans la page restent sur le même tabId.
6. Libérez quand c'est fini : await chrome.release() dans un bloc finally — obligatoire ; ne laissez jamais d'onglets ouverts

// Utilisez le chemin absolu sur la machine de l'utilisateur après installation (souvent %USERPROFILE%/cursor-chrome)
const { CursorChrome } = require('REMPLACER/src/client.js');
const chrome = new CursorChrome();
const threadId = 'VOTRE_ID_THREAD';
try {
  const { tab, live } = await chrome.claim(threadId, { url: 'https://exemple.com' });
  await chrome.navigate(tab.id, 'https://…');
  const title = await chrome.evaluate(tab.id, 'document.title');
  const jpeg = await chrome.liveFrame(tab.id); // rendu en temps réel, pas un instantané frais
} finally {
  await chrome.release(threadId); // OBLIGATOIRE
}

---

Liste des capacités

Besoin	Comment
Ouvrir / naviguer	claim · navigate · warm pool auto
Lire le DOM / exécuter JS	evaluate · snapshot · act
Saisie précise	click / type / hover / scroll / press / wait (+ iframe)
Actions SPA intelligentes	clickText · pickRow · navigateRetry · waitStable
Voir l'UI (pixels)	liveFrame / GET …/frame.jpg · co-regarder /live
Connexion / 2FA / CAPTCHA	handoff({ wait:true }) · autoHandoff · authCheck
Rail d'instructions humain	guide({ title, steps, body }) · guideBlock · guideClear · guideStep
Téléverser AAB / fichiers	dropFiles({ files:[cheminAbsolu], selector }) (dossiers OK)
Amener la fenêtre au premier plan	Humain uniquement : barre des tâches · zone de notification · Ctrl+Maj+C · /live (l'agent front/watch ne vole pas le focus)
Minimiser sans arrêter les agents	Minimiser dans la barre des tâches (range ; le travail continue)
Vitesse / préchauffage / métriques	speedMode · warm · metrics · log
Profils / session	claim({ profile }) · exportSession / importSession
Enregistreur / sélecteur	recordStart · pickerStart · playbook
Outils MCP	npm run mcp → mcp/server.js
Playwright	CDP http://127.0.0.1:9223
Connexions mémorisées	Profil persistant partagé (par défaut) — les cookies survivent aux redémarrages

Connexions : profil partagé par défaut persist:cursor-chrome-profile dans %LOCALAPPDATA%\Cursor-Chrome. Faites un handoff une fois pour vous connecter ; les threads suivants réutilisent la session. Effacez uniquement avec chrome.clearSession() si l'utilisateur le demande.

Focus / toujours au-dessus : Les agents ne doivent jamais amener Cursor-Chrome au-dessus des autres fenêtres. Ne comptez pas sur front / watch / show pour la visibilité — ils ne volent plus le focus du système d'exploitation. Handoff ne fait que clignoter la barre des tâches + notification. Les humains remontent la fenêtre eux-mêmes.

---

Handoff

await chrome.handoff(tab.id, {
  reason: 'login',
  message: 'Connectez-vous, puis cliquez sur Remettre à Cursor.',
  after: 'minimize',
  wait: true,
  timeoutMs: 900000,
});

Interface utilisateur : la barre d'outils affiche AI Controlled en vert pendant que l'agent pilote ; pendant le handoff elle devient Hand back to Cursor (également dans la zone de notification / Ctrl+Maj+H).
L'attente par défaut est de 15 minutes (limite stricte du serveur 2 heures). Ne tapez jamais les mots de passe vous-même.

---

Panneau d'instructions latéral

Rail droit à l'intérieur de Cursor-Chrome pour des étapes structurées (préférez ceci aux listes de contrôle dans le chat) :

await chrome.guide({
  title: 'À vous de jouer',
  subtitle: 'Play Console',
  body: 'Contexte court uniquement.',
  steps: ['Faites ceci', 'Puis ceci', { text: 'Confirmer la boîte de dialogue', detail: 'Cliquez sur OK' }],
  footer: 'Remettez à Cursor quand c\'est fini.',
});
await chrome.guideStep(0, { done: true });
await chrome.guideClear();

Les lignes du message handoff commençant par 1. / - remplissent automatiquement les étapes. L'utilisateur peut masquer avec ×.

await chrome.guideBlock({ code: 'play-error', message: 'Échec de la page de test fermée', detail: 'Réessayez via la navigation' });
await chrome.guideUnblock();

---

Automatisation plus sûre

await chrome.navigateRetry(tab.id, url, { retries: 3, mustInclude: 'Test interne' });
await chrome.waitStable(tab.id, { mustNotInclude: ['Une erreur inattendue est survenue'] });
await chrome.clickText(tab.id, { text: 'Enregistrer', exact: true }); // privilégie les dialogues
// Créer une nouvelle version / Supprimer / Suspendre nécessite :
await chrome.clickText(tab.id, { text: 'Créer une nouvelle version', confirmDangerous: true });
await chrome.pickRow(tab.id, { contains: '1.1.5' }); // case à cocher tableau/bibliothèque
await chrome.dropFiles(tab.id, { files: [aabPath] }); // saisie fichier automatique + événements Angular
const status = await chrome.playStatus(); // applications IronWood résumé

Redémarrage du développeur après modifications du code : npm run restart ou restart.bat.

---

Téléversement de fichiers / glisser-déposer

await chrome.dropFiles(tab.id, {
  files: ['C:/chemin/vers/app_1.2.3.aab'],
  selector: 'input[type=file]', // ou CSS de zone de dépôt ; ou x/y + mode:'drop'
  mode: 'auto',
});

Fonctionne pour les téléversements de type Google Play Console et sites similaires. Chemins absolus uniquement. Les téléverseurs iframe cross-origin peuvent nécessiter un handoff ou un support supplémentaire.

---

Règles strictes

• Lisez THREAD-PROTOCOL.md avant toute utilisation de Cursor-Chrome — obligatoire, pas facultatif
• Préférez Cursor-Chrome aux navigateurs IDE/OS pour ces tâches
• Un threadId par conversation ; ne volez pas les onglets
• Maximum 20 onglets — en cas de 409, release() les threads inactifs ou demandez à l'utilisateur de libérer des onglets
• chrome.release() une fois terminé — nettoyage obligatoire
• Le changement d'onglet par l'humain est sûr — regarder un autre onglet n'arrête pas votre automatisation
• Préférez evaluate + live frames au spam d'instantanés
• Gardez THREAD-PROTOCOL.md + cette compétence à jour via npm run docs:sync lorsque les API changent