브라우저 CLI: AI 코딩 에이전트를 위한 토큰 효율적인 브라우저 자동화 도구

Browser CLI의 기능

Browser CLI는 AI 코딩 에이전트의 토큰 오버헤드 문제를 해결하기 위해 개발된 브라우저 자동화 도구입니다. 제작자는 Playwright MCP 프로토콜 오버헤드로 인해 브라우저 검증이 세션당 약 30,000개의 토큰을 소모하고 있으며, 각 browser_navigate + browser_snapshot 호출이 JSON 스키마 프레이밍에서 약 1,500개의 토큰 비용이 든다는 사실을 발견했습니다.

해결책은 Bash 명령어를 통해 상호작용하는 지속형 헤드리스 Chromium 데몬입니다. 내부적으로 동일한 Playwright ARIA 스냅샷 기술을 사용하지만, 호출당 약 1,500개 대신 약 50-100개의 토큰만 소모합니다.

명령어와 사용법

사용 가능한 명령어:

• browser-cli goto https://example.com - URL로 이동
• browser-cli snapshot -i - @e 참조가 포함된 ARIA 트리
• browser-cli click @e3 - 참조로 클릭
• browser-cli fill @e5 "hello" - 입력 필드 채우기
• browser-cli css @e3 font-size - 계산된 CSS 값 가져오기
• browser-cli inspect @e3 - 전체 박스 모델 + 스타일
• browser-cli screenshot /tmp/page.png - 스크린샷
• browser-cli snapshot -D - 차이점: 마지막 스냅샷 이후 변경사항
• browser-cli responsive /tmp - 모바일/태블릿/데스크톱 크기로 스크린샷

서버는 첫 호출 시 자동 시작되며(약 3초), 이후 호출은 약 100-200ms 소요됩니다. 30분 동안 활성 상태를 유지하며 명령어 간 쿠키, 탭, 상태를 보존합니다.

토큰 절감 효과

토큰 비교:

• Playwright MCP: 호출당 약 1,500 토큰, 20회 호출 시 약 30,000 토큰
• Browser CLI: 호출당 약 75 토큰, 20회 호출 시 약 1,500 토큰

이는 브라우저 검증에 95%의 절감 효과입니다. 세션당 여러 작업을 수행하는 자동화 파이프라인에서는 이 효과가 빠르게 누적됩니다.

Playwright MCP를 넘어서는 기능

• CSS 검사 - css @e3 padding은 계산된 값을 반환합니다. inspect @e3은 전체 박스 모델 + 16개 주요 스타일을 JSON으로 제공합니다.
• 실시간 스타일 변형 - style @e3 color red와 style --undo. 소스 코드를 건드리지 않고 CSS 디버깅 가능.
• 스냅샷 차이 비교 - snapshot -D는 이전/이후 ARIA 트리를 비교합니다.
• 반응형 프리셋 - responsive /tmp는 모바일 + 태블릿 + 데스크톱 스크린샷을 한 번의 명령어로 촬영합니다.
• 인증 프로필 - handoff는 수동 SSO/MFA 로그인을 위해 가시적 Chrome을 열고, resume은 헤드리스 모드로 돌아가며, auth-save admin은 세션을 암호화합니다(AES-256). 다음에는 goto-auth https://app.com/dashboard --profile admin — 로그인 없이 사용 가능.
• 명령어 일괄 처리 - chain [["goto","url"],["snapshot","-i"],["console"]]는 여러 명령어를 한 번의 호출로 실행합니다.

기술적 구현

아키텍처: AI 에이전트 → Bash → CLI 클라이언트(bin/browse.mjs) → HTTP POST(localhost) → 서버(src/server.mjs) → Playwright API → Chromium(헤드리스).

순수 Node.js. Playwright가 유일한 의존성입니다. Bun 없음, Rust 없음, MCP 오버헤드 없음.

Claude Code 통합

전역 설치:

npm install -g @tuandm/browser-cli

.claude/settings.json에 추가:

{
  "permissions": {
    "allow": ["Bash(browser-cli*)"]
  }
}

.claude/rules/browser-cli.md에 규칙을 추가하여 Claude가 Playwright MCP 대신 Browser CLI를 사용하도록 지시합니다. 제작자는 5가지 평가 시나리오를 실행했으며, 규칙이 로드된 상태에서 Claude는 매번 올바른 명령어를 선택했습니다.

향후 마켓플레이스 배포를 위한 Claude Code 플러그인(plugin.json 포함)으로도 제공됩니다.

영감과 기술

Garry Tan의 gstack에서 영감을 받았으며, 이는 AI 에이전트를 위한 지속형 Chromium CLI 접근 방식을 선구했습니다. 핵심 통찰은 Bash 명령어가 브라우저 자동화에 있어 MCP보다 훨씬 더 토큰 효율적이라는 점이었습니다. 기반 기술은 Microsoft의 Playwright입니다.