citrolabs/ego-lite 딥다이브
— "AI 브라우저"인데, 이 저장소엔 LLM 코드가 한 줄도 없다

1프로젝트 한 줄 요약

요즘 "AI 브라우저"가 쏟아진다. OpenAI의 ChatGPT Atlas, Perplexity의 Comet, The Browser Company의 Dia… 대부분 브라우저 안에 자기네 AI를 박아넣은 형태다. ego lite는 여기서 방향을 튼다. ego lite의 핵심 주장은 "우리 AI가 똑똑하다"가 아니라, "당신이 이미 쓰는 에이전트(Claude Code, Codex…)에게 진짜 브라우저를 통째로 내어준다"이다.

동작을 한 문장으로 압축하면 이렇다. 에이전트가 자바스크립트를 한 덩어리 짜서 ego-browser 명령의 표준입력으로 밀어넣으면 → 저장소의 하네스(harness)가 그 코드를 실행하며 page·browser·taskSpaces 같은 브라우저 조종 헬퍼를 주입하고 → 각 헬퍼는 CDP 메시지로 번역돼 클로즈드 브라우저에 전달된다. 결과(페이지 스냅샷·DOM·다운로드)는 console.log로만 에이전트에게 돌아온다.

2왜 주목받는가

ego lite가 트렌딩에 오른 건 별점 때문이 아니다. 분석 시점 기준 별 47개, 포크 0, 커밋 34개에 불과하다. TrendShift 상위 순위의 굵은 숫자는 별 수가 아니라 "지금 얼마나 빠르게 화제가 번지는가"(모멘텀)를 뜻한다(프로젝트 규칙에도 명시). ego lite는 두 개의 뜨거운 흐름이 겹치는 지점에 정확히 자리 잡아 모멘텀을 얻었다.

• AI 브라우저 전쟁: Atlas·Comet·Dia·Arc가 "브라우저 + AI"를 놓고 경쟁 중.
• 에이전트 스킬(agent skills) 붐: Claude Code용 스킬을 배포·공유하는 생태계(skills.sh, ClawHub 등)가 폭발.

ego lite의 포지셔닝은 README의 정면 비교표로 요약된다. 기존 두 진영을 각각 저격한다.

기술적 후크도 있다. 저장소는 Vercel의 agent-browser와 비교해 복잡한 작업에서 최대 2.5배 빠르고 토큰도 크게 아낀다고 주장한다(docs/assets/ego-vs-agent-benchmark.png). 이 속도의 비결은 뒤(4장)에서 볼 "CLI를 여러 번 왕복하지 말고, 전 과정을 코드 한 덩어리로 짜서 한 번에 실행"이라는 설계에 있다. 왕복(round-trip)이 줄면 지연도, 토큰도 준다.

3기술 스택 전체 지도

이 저장소를 처음 열면 "AI 브라우저치고 너무 가벼운데?"라는 인상을 받는다. 무거운 프레임워크가 없기 때문이다. 코어는 순수 TypeScript이고, 브라우저를 조종하는 데 Playwright도 Puppeteer도 쓰지 않으며, LLM 호출 코드도 MCP도 없다. 세 겹으로 나눠 지도를 그려보자.

① 하네스 코어 (이 저장소의 심장) — package/ego-browser

② 브라우저 바이너리 (저장소 밖, 클로즈드) — ego lite.app

진짜 브라우저는 Chromium을 커널 수준까지 커스터마이즈한 클로즈드 소스 macOS 앱이다. "가장 강력한 스냅샷", "Task Space(격리 컨텍스트)", "로그인 세션 상속" 같은 해자(moat)에 해당하는 기능은 전부 이 바이너리 안에 있다. 하네스는 globalThis.ego.snapshot(), globalThis.ego.sendCDPMessage(), globalThis.ego.createTaskSpace() 같은 브리지 함수로 이 능력을 빌려 쓴다.

③ 배포·생태계 인프라 — .github/, .claude-plugin/, skills/

• 플러그인 등록: .claude-plugin/marketplace.json(Claude Code용), .codex-plugin/plugin.json(Codex용). 에이전트 CLI가 이 스킬을 "플러그인"으로 인식하게 하는 매니페스트.
• 스킬 자동 배포: .github/workflows/publish-ego-browser-skill.yml이 태그를 push하면 ClawHub·SkillHub 두 마켓에 동시 배포한다. 릴리스 아카이브에 토큰 유출 방지 grep(clh_|skh_|pt-)까지 넣어둔 실전 파이프라인.
• 화면 녹화: video-recorder.ts + driver/screencast.ts가 CDP 스크린캐스트를 받아 ffmpeg로 VP8 WebM을 만든다(선택 기능, ffmpeg 필요).

4아키텍처 심화 분석

전체 데이터 흐름

핵심 패턴 ① "CLI base가 아니라 Code base" — new AsyncFunction 주입

이 프로젝트의 정체성이 담긴 5줄이다. 에이전트가 넘긴 코드 문자열을 비동기 함수로 감싸서, 브라우저 조종 헬퍼들을 함수 인자로 주입한 뒤 한 번에 실행한다(src/run.ts).

// src/run.ts — 에이전트 JS를 헬퍼 주입해 한 번에 실행
const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
const names  = Object.keys(context);   // page, browser, taskSpaces, cdp, help ...
const values = Object.values(context);
const fn = new AsyncFunction(...names, `"use strict";\n${code}`);
await fn(...values);                    // 헬퍼가 지역변수처럼 보이는 채로 실행

헬퍼를 import하지 않는데도 에이전트 코드에서 page·browser가 전역처럼 보이는 이유가 바로 이것이다. 이름이 곧 API다. 그리고 "관찰→호출→관찰"을 CLI로 여러 번 왕복하는 대신, 예측 가능한 전 과정을 하나의 JS 블록에 담아 왕복을 없앤다 — 2장에서 본 속도·토큰 이득의 정체다. 스킬 문서(SKILL.md)는 이를 규범으로 못 박는다: "기본은 브라우저 작업 전체를 한 번의 Bash 호출로."

핵심 패턴 ② 자가 치유 CDP 세션 (2초 TTL 캐시)

장시간 도는 런타임에서 CDP 세션은 자꾸 끊긴다(탭 전환·페이지 이동 등). browser-runtime.ts는 세션 id를 2초만 캐싱하고, "Session not found" 류 에러를 감지하면 조용히 재부착(re-attach) 후 1회 재시도한다. 에이전트는 끊김을 눈치채지 못한다.

// src/browser-runtime.ts — 세션 잃으면 재부착 후 재시도 (요약)
try {
  return await rawCdp(method, params, session, timeoutMs);
} catch (error) {
  const lost = SESSION_LOST.test(error?.message || "");
  if (lost && !isBrowserLevel(method)) {
    invalidateSession();
    const fresh = await ensureSession();  // 새 sessionId 확보
    return rawCdp(method, params, fresh, timeoutMs);
  }
  throw error;
}

핵심 패턴 ③ "@N ref"와 스냅샷 — 에이전트가 요소를 가리키는 법

에이전트는 픽셀 좌표로 클릭하지 않는다. 대신 snapshot()이 페이지를 텍스트로 요약하면서 클릭 가능한 요소마다 @21, @34 같은 ref 번호를 붙인다. 이 번호의 정체는 backendNodeId(브라우저 내부 DOM 노드 식별자)다. 스냅샷을 새로 뜰 때마다 ref 맵을 지우고 다시 만들기 때문에, ref는 "가장 최근 스냅샷 안에서만" 유효하다. 스냅샷 계산 자체는 커널 수준 커스텀 덕에 깊게 중첩된 iframe까지 네이티브 브라우저가 처리한다(driver/observe.ts → browserEgo().snapshot()).

핵심 패턴 ④ Task Space = "나란히(parallel)"의 실제 구현

README 태그라인의 "parallel"이 마케팅 수사가 아니라 코드로 존재한다. Task Space는 사용자 로그인 상태를 상속하는 격리 브라우징 컨텍스트(자체 탭을 가진다)이고, 각 Space에는 소유권(ownership)이 붙는다.

에이전트는 자기 소유 Space에서만 일하고, 사람 소유 Space는 건드리지 않는다. 그래서 사람과 에이전트가 같은 브라우저를 쓰면서도 서로의 탭을 빼앗지 않는다. 로그인이 필요하면 handOffTaskSpace로 사람에게 넘기고, waitForAgentControl로 다시 받는다. 작업 완료(completeTaskSpace)는 브라우저 조작과 분리된 별도 Bash 호출로만 하도록 강제해, 미완 작업을 "다 됐다"고 착각하는 사고를 막는다.

5디렉토리 구조 해부

구조를 읽는 핵심 감각: package/ego-browser는 "실행되는 코드"(당신이 npm run build로 만드는 CLI), skills/ego-browser는 "에이전트에게 주는 설명서 + 사이트 지식"이다. 빌드 시 build.mjs가 skills/ego-browser를 최종 산출물 안으로 복사해 하나로 묶는다. 즉 코드와 문서가 한 배포물로 함께 나간다.

6학습 포인트

기술별 배울 것

실습으로 확인해볼 개념

7시스템 요구사항 · 빌드/실행

에이전트로 바로 쓰기 (가장 흔한 시나리오)

# 스킬만 먼저 추가 — 첫 브라우저 작업 때 앱 설치를 유도한다
npx skills add citrolabs/ego-lite

# 또는 설치 스크립트로 DMG 자동 설치(+quarantine 제거+실행)
sh skills/ego-browser/scripts/install.sh

개발자로 직접 빌드 (package/ego-browser/에서)

npm run build      # esbuild + rollup → dist/out/index.js 단일 파일
npm test           # build → tsc --noEmit 타입체크 → node --test
npm run e2e        # 실브라우저 Task Space e2e

# 로컬 실행 (실제 브라우저 작업엔 ego 런타임 필요)
node dist/out/index.js <<'JS'
  await page.goto("https://example.com");
  console.log(await page.title());
JS
node dist/out/index.js --doctor   # 환경 진단

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

1주차 — CDP와 브라우저 자동화의 밑바닥

Chrome DevTools Protocol 공식 문서에서 Target·Page·Runtime·Input·DOM 도메인을 훑는다. chrome --remote-debugging-port=9222로 띄우고 ws://에 직접 붙어 JSON-RPC를 주고받아 본다. 그다음 Puppeteer/Playwright 소스에서 CDPSession이 어떻게 이걸 감싸는지 비교하면, ego lite가 "왜 래퍼 없이 직접 갔는지"가 보인다.

2주차 — 코드 실행 모델과 샌드박싱

new Function/AsyncFunction, vm 모듈, 그리고 "왜 임의 코드 실행이 위험한가/언제 안전한가"를 공부한다. ego lite가 로컬·신뢰된 에이전트라는 전제 위에서만 이 패턴을 쓰는 이유를 이해한다. DSL·플러그인 런타임 설계로 시야를 넓힌다.

3주차 — 에이전트 스킬 생태계

Anthropic의 Claude Code 스킬/플러그인 구조, SKILL.md 규범, agentskills.io 스펙을 읽는다. ego lite의 marketplace.json·publish-ego-browser-skill.yml을 뜯어보며 "스킬을 만들어 여러 마켓에 배포"하는 실전 파이프라인을 재현해 본다.

4주차 — 신뢰성 있는 자동화 엔지니어링

자가 치유 세션·에러 택소노미·이벤트 큐·타임아웃/하드스톱 같은 "오래 도는 자동화가 안 죽게 하는 기술"을 모아 학습한다. browser-runtime.ts·ego-errors.ts·output-sink.ts를 교재로, 실패를 우아하게 다루는 런타임 설계를 익힌다.

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/citrolabs/ego-lite (MIT · npm ego-browser-v2 0.1.0 · ★47)
• TrendShift: trendshift.io/repositories/42334 (2026-07-24 Daily #5)
• 문서 사이트: lite.ego.app (설치 가이드·데모)
• 핵심 문서: AGENTS.md(아키텍처, 필독) · README.md(비전·비교표) · skills/ego-browser/SKILL.md(에이전트 규범)
• 핵심 소스: package/ego-browser/src/run.ts(코드 주입 실행) · browser-runtime.ts(CDP·세션) · element-resolver.ts(요소 해석) · helpers.ts(헬퍼 단일 진실원) · driver/observe.ts(스냅샷)
• 바로 써볼 것: npx skills add citrolabs/ego-lite (macOS + Claude Code/Codex 필요)
• 배경 개념: Chrome DevTools Protocol · Playwright/Puppeteer 내부 · Claude Code 스킬/플러그인 · agentskills.io 스펙 · new Function 코드 실행 모델