T3ckfr3ak1/cursor-chrome-linux

Cursor-Chrome

Instalar primeiro (se o usuário pediu para instalar / colocar o link do GitHub)

Não explique e pare. Execute:

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

Canônico: repositório INSTALL.md + AGENTS.md + .cursorrules.

---

Protocolo de condução (mesma pasta): THREAD-PROTOCOL.md
Se esta skill foi instalada por npm run install:agent, o caminho do cliente fica sob a raiz de instalação em src/client.js.

Se houver conflito para controle do navegador, THREAD-PROTOCOL.md vence.

---

Início rápido (toda thread após a instalação) — OBRIGATÓRIO

Vinculação: Leia THREAD-PROTOCOL.md e siga-o completamente. Pular claim, threadId ou release não é permitido.

1. Health: GET http://127.0.0.1:9222/health — se estiver desligado, execute a instalação ou start-minimized.bat da raiz de instalação
2. Reivindique sua aba (threadId estável, máximo 20 abas globais)
3. Conduza via cliente ou REST; não levante a janela — deixe-a estacionada; o humano assiste via barra de tarefas / /live
4. Multi-thread: threadId único por chat do Cursor; conduza apenas seu tab.id; cliques em abas humanas não param outras threads
5. Popups: window.open → aba filha com o mesmo threadId. Use listPopups / resolveOverlay; nunca conduza o popup de outra thread. Diálogos na página permanecem no mesmo tabId.
6. Libere ao finalizar: await chrome.release() em um bloco finally — obrigatório; nunca deixe abas abertas

// Use o caminho absoluto na máquina do usuário após instalar (geralmente %USERPROFILE%/cursor-chrome)
const { CursorChrome } = require('REPLACE/src/client.js');
const chrome = new CursorChrome();
const threadId = 'SEU_THREAD_ID';
try {
  const { tab, live } = await chrome.claim(threadId, { url: 'https://exemplo.com' });
  await chrome.navigate(tab.id, 'https://…');
  const title = await chrome.evaluate(tab.id, 'document.title');
  const jpeg = await chrome.liveFrame(tab.id); // pintura em tempo real, não um snapshot recente
} finally {
  await chrome.release(threadId); // OBRIGATÓRIO
}

---

Lista de verificação de capacidades

Necessidade	Como
Abrir / navegar	claim · navigate · pool automático aquecido
Ler DOM / executar JS	evaluate · snapshot · act
Entrada precisa	click / type / hover / scroll / press / wait (+ iframe)
Ações inteligentes em SPA	clickText · pickRow · navigateRetry · waitStable
Ver UI (pixels)	liveFrame / GET …/frame.jpg · co-visualizar /live
Login / 2FA / CAPTCHA	handoff({ wait:true }) · autoHandoff · authCheck
Trilha de instrução humana	guide({ title, steps, body }) · guideBlock · guideClear · guideStep
Upload de AAB / arquivos	dropFiles({ files:[caminhoAbsoluto], selector }) (pastas OK)
Trazer janela para frente	Apenas humano: barra de tarefas · bandeja · Ctrl+Shift+C · /live (agente front/watch não roubam foco)
Minimizar sem parar agentes	Minimizar na barra de tarefas (estaciona; trabalho continua)
Velocidade / aquecimento / métricas	speedMode · warm · metrics · log
Perfis / sessão	claim({ profile }) · exportSession / importSession
Gravador / seletor	recordStart · pickerStart · playbook
Ferramentas MCP	npm run mcp → mcp/server.js
Playwright	CDP http://127.0.0.1:9223
Logins memorizados	Perfil persistente compartilhado (padrão) — cookies sobrevivem a reinicializações

Logins: perfil compartilhado padrão persist:cursor-chrome-profile em %LOCALAPPDATA%\Cursor-Chrome. Faça handoff uma vez para fazer login; threads posteriores reutilizam a sessão. Limpe apenas com chrome.clearSession() se o usuário pedir.

Foco / sempre no topo: Agentes nunca devem puxar o Cursor-Chrome sobre outras janelas. Não confie em front / watch / show para visibilidade — eles não roubam mais o foco do SO. Handoff apenas pisca a barra de tarefas + notificação. Humanos elevam a janela eles mesmos.

---

Handoff

await chrome.handoff(tab.id, {
  reason: 'login',
  message: 'Faça login e clique em "Devolver ao Cursor".',
  after: 'minimize',
  wait: true,
  timeoutMs: 900000,
});

Interface do usuário: a barra de ferramentas mostra Controlado por IA em verde enquanto o agente conduz; durante o handoff torna-se Devolver ao Cursor (também na bandeja / Ctrl+Shift+H).
O tempo de espera padrão é de 15 minutos (limite máximo do servidor 2 horas). Nunca digite senhas você mesmo.

---

Barra de instruções lateral

Trilha direita dentro do Cursor-Chrome para etapas organizadas (prefira isso a listas de verificação no chat):

await chrome.guide({
  title: 'Sua vez',
  subtitle: 'Play Console',
  body: 'Apenas contexto breve.',
  steps: ['Faça isso', 'Depois isso', { text: 'Confirme o diálogo', detail: 'Clique em OK' }],
  footer: 'Devolva ao Cursor quando terminar.',
});
await chrome.guideStep(0, { done: true });
await chrome.guideClear();

Linhas de message de handoff iniciadas com 1. / - preenchem etapas automaticamente. O usuário pode ocultar com ×.

await chrome.guideBlock({ code: 'play-error', message: 'Falha na página de teste fechado', detail: 'Tente novamente via navegação' });
await chrome.guideUnblock();

---

Automação mais segura

await chrome.navigateRetry(tab.id, url, { retries: 3, mustInclude: 'Teste interno' });
await chrome.waitStable(tab.id, { mustNotInclude: ['Ocorreu um erro inesperado'] });
await chrome.clickText(tab.id, { text: 'Salvar', exact: true }); // prefere diálogos
// Criar novo lançamento / Excluir / Parar requer:
await chrome.clickText(tab.id, { text: 'Criar novo lançamento', confirmDangerous: true });
await chrome.pickRow(tab.id, { contains: '1.1.5' }); // caixa de seleção de tabela/biblioteca
await chrome.dropFiles(tab.id, { files: [aabPath] }); // entrada de arquivo automática + eventos de mudança Angular
const status = await chrome.playStatus(); // scraping de resumo de apps IronWood

Reinicialização de desenvolvimento após alterações de código: npm run restart ou restart.bat.

---

Upload de arquivo / arrastar e soltar

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

Funciona para uploads no estilo Google Play Console e sites similares. Apenas caminhos absolutos. Uploaders em iframes entre origens podem precisar de handoff ou suporte extra.

---

Regras rígidas

• Leia THREAD-PROTOCOL.md antes de qualquer uso do Cursor-Chrome — obrigatório, não opcional
• Prefira Cursor-Chrome sobre navegadores IDE/SO para estas tarefas
• Um threadId por conversa; não roube abas
• Máximo de 20 abas — em 409, release() threads ociosas ou peça ao usuário para liberar abas
• chrome.release() ao finalizar — limpeza obrigatória
• Troca de abas pelo humano é segura — assistir outra aba não para sua automação
• Prefira evaluate + quadros ao vivo em vez de spam de snapshots
• Mantenha THREAD-PROTOCOL.md + esta skill atualizados via npm run docs:sync quando as APIs mudarem