T3ckfr3ak1/cursor-chrome-linux

Cursor-Chrome

Instalación primero (si el usuario pidió instalar / soltó el enlace de GitHub)

No expliques y detente. Ejecuta:

• Clonar abierto como espacio de trabajo → npm run install:agent
• Solo URL (Windows) →
  irm https://raw.githubusercontent.com/T3ckfr3ak1/cursor-chrome-public/main/scripts/remote-bootstrap.ps1 | iex
• Comprobar: GET http://127.0.0.1:9222/health → "ok": true

Canónico: repositorio INSTALL.md + AGENTS.md + .cursorrules.

---

Protocolo de conducción (misma carpeta): THREAD-PROTOCOL.md
Si esta skill fue instalada mediante npm run install:agent, la ruta del cliente está bajo la raíz de instalación en src/client.js.

Si hay conflicto sobre el control del navegador, THREAD-PROTOCOL.md tiene prioridad.

---

Inicio rápido (cada hilo después de la instalación) — OBLIGATORIO

Vinculación: Lee THREAD-PROTOCOL.md y síguelo completamente. Saltarse claim, threadId o release no está permitido.

1. Salud: GET http://127.0.0.1:9222/health — si está caído, ejecuta la instalación o start-minimized.bat desde la raíz de instalación
2. Reclama tu pestaña (threadId estable, máximo 20 pestañas globales)
3. Conduce mediante cliente o REST; no levantes la ventana — déjala estacionada; el humano observa a través de la barra de tareas / /live
4. Multihilo: threadId único por chat de Cursor; conduce solo tu tab.id; los clics del humano en otras pestañas no detienen otros hilos
5. Ventanas emergentes: window.open → pestaña hija con el mismo threadId. Usa listPopups / resolveOverlay; nunca conduzcas la ventana emergente de otro hilo. Los diálogos en página permanecen en el mismo tabId.
6. Libera al terminar: await chrome.release() en un bloque finally — obligatorio; nunca dejes pestañas abiertas

// Usa ruta absoluta en la máquina del usuario después de instalar (a menudo %USERPROFILE%/cursor-chrome)
const { CursorChrome } = require('REEMPLAZAR/src/client.js');
const chrome = new CursorChrome();
const threadId = 'TU_THREAD_ID';
try {
  const { tab, live } = await chrome.claim(threadId, { url: 'https://ejemplo.com' });
  await chrome.navigate(tab.id, 'https://…');
  const title = await chrome.evaluate(tab.id, 'document.title');
  const jpeg = await chrome.liveFrame(tab.id); // pintura en tiempo real, no una captura nueva
} finally {
  await chrome.release(threadId); // OBLIGATORIO
}

---

Lista de capacidades

Necesidad	Cómo
Abrir / navegar	claim · navigate · pool cálido automático
Leer DOM / ejecutar JS	evaluate · snapshot · act
Entrada precisa	click / type / hover / scroll / press / wait (+ iframe)
Acciones SPA inteligentes	clickText · pickRow · navigateRetry · waitStable
Ver UI (píxeles)	liveFrame / GET …/frame.jpg · co-ver /live
Inicio de sesión / 2FA / CAPTCHA	handoff({ wait:true }) · autoHandoff · authCheck
Guía de instrucciones humanas	guide({ title, steps, body }) · guideBlock · guideClear · guideStep
Subir AAB / archivos	dropFiles({ files:[rutaAbsoluta], selector }) (carpetas OK)
Traer ventana al frente	Solo humano: barra de tareas · bandeja · Ctrl+Mayús+C · /live (el agente front/watch no roba el foco)
Minimizar sin detener agentes	Minimizar en barra de tareas (estaciona; el trabajo continúa)
Velocidad / cálido / métricas	speedMode · warm · metrics · log
Perfiles / sesión	claim({ profile }) · exportSession / importSession
Grabador / selector	recordStart · pickerStart · playbook
Herramientas MCP	npm run mcp → mcp/server.js
Playwright	CDP http://127.0.0.1:9223
Inicios de sesión recordados	Perfil persistente compartido (predeterminado) — las cookies sobreviven a reinicios

Inicios de sesión: perfil compartido predeterminado persist:cursor-chrome-profile en %LOCALAPPDATA%\Cursor-Chrome. Entrega el control una vez para iniciar sesión; hilos posteriores reutilizan la sesión. Limpia solo con chrome.clearSession() si el usuario lo pide.

Foco / siempre encima: Los agentes nunca deben arrebatar Cursor-Chrome sobre otras ventanas. No confíes en front / watch / show para visibilidad — ya no roban el foco del SO. La entrega de control solo parpadea la barra de tareas + notificación. Los humanos suben la ventana ellos mismos.

---

Entrega de control (Handoff)

await chrome.handoff(tab.id, {
  reason: 'login',
  message: 'Inicia sesión, luego haz clic en Devolver a Cursor.',
  after: 'minimize',
  wait: true,
  timeoutMs: 900000,
});

Interfaz de usuario: la barra de herramientas muestra Controlado por IA en verde mientras el agente conduce; durante la entrega se convierte en Devolver a Cursor (también en bandeja / Ctrl+Mayús+H).
La espera predeterminada es 15 minutos (límite máximo del servidor 2 horas). Nunca escribas contraseñas tú mismo.

---

Barra lateral de instrucciones

Panel derecho dentro de Cursor-Chrome para pasos organizados (prefiere esto sobre listas de verificación en chat):

await chrome.guide({
  title: 'Tu turno',
  subtitle: 'Play Console',
  body: 'Solo contexto breve.',
  steps: ['Haz esto', 'Luego esto', { text: 'Confirma diálogo', detail: 'Haz clic en OK' }],
  footer: 'Devuelve a Cursor cuando termines.',
});
await chrome.guideStep(0, { done: true });
await chrome.guideClear();

Las líneas del message de entrega que comienzan con 1. / - completan pasos automáticamente. El usuario puede ocultar con ×.

await chrome.guideBlock({ code: 'play-error', message: 'Falló la página de pruebas cerradas', detail: 'Reintenta mediante navegación' });
await chrome.guideUnblock();

---

Automatización más segura

await chrome.navigateRetry(tab.id, url, { retries: 3, mustInclude: 'Pruebas internas' });
await chrome.waitStable(tab.id, { mustNotInclude: ['Ha ocurrido un error inesperado'] });
await chrome.clickText(tab.id, { text: 'Guardar', exact: true }); // prefiere diálogos
// Crear nueva versión / Eliminar / Detener requieren:
await chrome.clickText(tab.id, { text: 'Crear nueva versión', confirmDangerous: true });
await chrome.pickRow(tab.id, { contains: '1.1.5' }); // casilla de verificación en tabla/biblioteca
await chrome.dropFiles(tab.id, { files: [aabPath] }); // entrada de archivo automática + eventos de cambio de Angular
const status = await chrome.playStatus(); // aplicaciones IronWood resumen de extracción

Reinicio de desarrollo después de cambios de código: npm run restart o restart.bat.

---

Subida de archivos / arrastrar y soltar

await chrome.dropFiles(tab.id, {
  files: ['C:/ruta/a/app_1.2.3.aab'],
  selector: 'input[type=file]', // o CSS de zona de soltar; o x/y + mode:'drop'
  mode: 'auto',
});

Funciona para subidas estilo Google Play Console y sitios similares. Solo rutas absolutas. Los cargadores de iframe de origen cruzado pueden requerir entrega de control o soporte adicional.

---

Reglas estrictas

• Lee THREAD-PROTOCOL.md antes de cualquier uso de Cursor-Chrome — obligatorio, no opcional
• Prefiere Cursor-Chrome sobre navegadores IDE/SO para estas tareas
• Un threadId por conversación; no robes pestañas
• Máximo 20 pestañas — en error 409, release() hilos inactivos o pide al usuario liberar pestañas
• chrome.release() al terminar — limpieza obligatoria
• El cambio de pestañas del humano es seguro — ver otra pestaña no detiene tu automatización
• Prefiere evaluate + marcos en vivo sobre spam de capturas
• Mantén THREAD-PROTOCOL.md + esta skill actualizadas mediante npm run docs:sync cuando las APIs cambien