Cursor-Chrome
먼저 설치 (사용자가 설치 요청 / GitHub 링크를 드롭한 경우)
설명하지 말고 바로 실행하세요:
- 클론 후 워크스페이스 열기 →
npm run install:agent - URL만 있는 경우 (Windows) →
irm https://raw.githubusercontent.com/T3ckfr3ak1/cursor-chrome-public/main/scripts/remote-bootstrap.ps1 | iex - 확인:
GET http://127.0.0.1:9222/health→"ok": true
공식 문서: 저장소 INSTALL.md + AGENTS.md + .cursorrules
구동 프로토콜 (같은 폴더): THREAD-PROTOCOL.md
이 스킬이 npm run install:agent로 설치된 경우, 클라이언트 경로는 설치 루트의 src/client.js에 있습니다.
브라우저 제어와 관련해 충돌이 발생하면 THREAD-PROTOCOL.md가 우선합니다.
빠른 시작 (설치 이후 모든 스레드) — 필수
바인딩: THREAD-PROTOCOL.md를 읽고 완전히 따르세요.
claim,threadId,release를 건너뛰는 것은 허용되지 않습니다.
- 건강 상태:
GET http://127.0.0.1:9222/health— 다운된 경우 설치를 실행하거나 설치 루트에서start-minimized.bat실행 - 탭 점유하기 (안정적인
threadId, 최대 20개 글로벌 탭) - 클라이언트 또는 REST를 통해 구동; 창을 올리지 마세요 — 그대로 두세요; 사용자는 작업 표시줄 /
/live를 통해 확인 - 멀티스레드: Cursor 채팅마다 고유한
threadId; 자신의tab.id만 구동; 사용자 탭 클릭은 다른 스레드를 중단시키지 않음 - 팝업:
window.open→ 동일한threadId를 가진 자식 탭.listPopups/resolveOverlay사용; 다른 스레드의 팝업은 절대 구동하지 마세요. 페이지 내 대화상자는 동일한 tabId에 유지됩니다. - 완료 시 해제:
await chrome.release()를finally블록 안에서 호출하세요 — 필수; 탭을 열어둔 상태로 두지 마세요
// 설치 후 사용자 머신의 절대 경로 사용 (보통 %USERPROFILE%/cursor-chrome)
const { CursorChrome } = require('REPLACE/src/client.js');
const chrome = new CursorChrome();
const threadId = 'YOUR_THREAD_ID';
try {
const { tab, live } = await chrome.claim(threadId, { url: 'https://example.com' });
await chrome.navigate(tab.id, 'https://…');
const title = await chrome.evaluate(tab.id, 'document.title');
const jpeg = await chrome.liveFrame(tab.id); // 실시간 페인트, 새 스냅샷 아님
} finally {
await chrome.release(threadId); // 필수
}
기능 체크리스트
| 필요 기능 | 방법 |
|---|---|
| 열기 / 탐색 | claim · navigate · 웜 풀 자동 |
| DOM 읽기 / JS 실행 | evaluate · snapshot · act |
| 정밀 입력 | click / type / hover / scroll / press / wait (+ iframe) |
| 스마트 SPA 작업 | clickText · pickRow · navigateRetry · waitStable |
| UI 보기 (픽셀) | liveFrame / GET …/frame.jpg · 공동 시청 /live |
| 로그인 / 2FA / CAPTCHA | handoff({ wait:true }) · autoHandoff · authCheck |
| 사용자 안내 레일 | guide({ title, steps, body }) · guideBlock · guideClear · guideStep |
| AAB / 파일 업로드 | dropFiles({ files:[절대경로], selector }) (폴더 가능) |
| 창 앞으로 가져오기 | 사용자만: 작업 표시줄 · 트레이 · Ctrl+Shift+C · /live (에이전트 front/watch는 포커스를 빼앗지 않음) |
| 에이전트 중단 없이 최소화 | 작업 표시줄 최소화 (숨김, 작업 계속) |
| 속도 / 웜 / 메트릭 | speedMode · warm · metrics · log |
| 프로필 / 세션 | claim({ profile }) · exportSession / importSession |
| 레코더 / 선택기 | recordStart · pickerStart · playbook |
| MCP 도구 | npm run mcp → mcp/server.js |
| Playwright | CDP http://127.0.0.1:9223 |
| 저장된 로그인 | 공유 영구 프로필 (기본값) — 쿠키 재시작 후에도 유지 |
로그인: 기본 공유 프로필 persist:cursor-chrome-profile (%LOCALAPPDATA%\Cursor-Chrome 위치). 한 번 핸드오프하여 로그인하면 이후 스레드는 세션을 재사용합니다. 사용자가 요청할 경우에만 chrome.clearSession()으로 삭제하세요.
포커스 / 항상 위에: 에이전트는 절대 Cursor-Chrome을 다른 창 위로 가져와서는 안 됩니다. 가시성을 위해 front / watch / show에 의존하지 마세요 — 더 이상 OS 포커스를 빼앗지 않습니다. 핸드오프는 작업 표시줄 알림을 깜빡일 뿐입니다. 사용자가 직접 창을 올립니다.
핸드오프
await chrome.handoff(tab.id, {
reason: 'login',
message: '로그인하고, 완료되면 "Cursor로 다시 넘기기"를 클릭하세요.',
after: 'minimize',
wait: true,
timeoutMs: 900000,
});
사용자 UI: 에이전트가 구동 중일 때 도구 모음에 초록색 AI 제어 중이 표시됩니다. 핸드오프 중에는 Cursor로 다시 넘기기로 바뀝니다 (트레이 / Ctrl+Shift+H도 가능).
기본 대기 시간은 15분입니다 (서버 하드캡 2시간). 비밀번호를 직접 입력하지 마세요.
안내 사이드바
Cursor-Chrome 내부 오른쪽 레일에 단계별 안내 표시 (채팅 체크리스트보다 선호):
await chrome.guide({
title: '당신의 차례',
subtitle: 'Play Console',
body: '짧은 컨텍스트만.',
steps: ['이것을 하세요', '그 다음 이것', { text: '대화상자 확인', detail: '확인 클릭' }],
footer: '완료되면 Cursor로 다시 넘기기',
});
await chrome.guideStep(0, { done: true });
await chrome.guideClear();
핸드오프 message 줄이 1. / -로 시작하면 자동으로 단계가 채워집니다. 사용자는 ×로 숨길 수 있습니다.
await chrome.guideBlock({ code: 'play-error', message: '클로즈드 테스팅 페이지 실패', detail: '탐색을 통해 재시도' });
await chrome.guideUnblock();
더 안전한 자동화
await chrome.navigateRetry(tab.id, url, { retries: 3, mustInclude: '내부 테스트' });
await chrome.waitStable(tab.id, { mustNotInclude: ['예상치 못한 오류가 발생했습니다'] });
await chrome.clickText(tab.id, { text: '저장', exact: true }); // 대화상자 선호
// 새 릴리스 생성 / 삭제 / 중단 필요 시:
await chrome.clickText(tab.id, { text: '새 릴리스 생성', confirmDangerous: true });
await chrome.pickRow(tab.id, { contains: '1.1.5' }); // 라이브러리/테이블 체크박스
await chrome.dropFiles(tab.id, { files: [aabPath] }); // 자동 파일 입력 + Angular 변경 이벤트
const status = await chrome.playStatus(); // IronWood 앱 스크랩 요약
코드 변경 후 개발자 재시작: npm run restart 또는 restart.bat.
파일 업로드 / 드래그-드롭
await chrome.dropFiles(tab.id, {
files: ['C:/path/to/app_1.2.3.aab'],
selector: 'input[type=file]', // 또는 드롭존 CSS; 또는 x/y + mode:'drop'
mode: 'auto',
});
Google Play Console 스타일 업로드 및 유사한 사이트에서 작동합니다. 절대 경로만 허용됩니다. 교차 출처 iframe 업로더는 핸드오프 또는 추가 지원이 필요할 수 있습니다.
엄격한 규칙
- Cursor-Chrome을 사용하기 전에 THREAD-PROTOCOL.md를 읽으세요 — 필수, 선택 아님
- 이러한 작업의 경우 IDE/OS 브라우저보다 Cursor-Chrome을 우선 사용하세요
- 대화당 하나의
threadId; 탭을 훔치지 마세요 - 최대 20개 탭 — 409 오류 발생 시 유휴 스레드
release()또는 사용자에게 탭 해제 요청 - 작업 완료 시
chrome.release()— 필수 정리 - 사용자 탭 전환은 안전합니다 — 다른 탭을 보더라도 자동화가 중단되지 않습니다
- 스냅샷 남발보다
evaluate+ 라이브 프레임을 선호하세요 - API 변경 시
npm run docs:sync를 통해THREAD-PROTOCOL.md+ 이 스킬을 최신 상태로 유지하세요