Bridgic Browser는 Playwright를 기반으로 구축된 LLM(대규모 언어 모델) 구동 브라우저 자동화용 Python 라이브러리입니다. CLI 도구, Python 도구 및 AI 에이전트를 위한 스킬을 포함하고 있습니다.종합적인 CLI 도구: 15개 카테고리에 걸쳐 67개의 도구가 정리되어 있으며, 모든 AI 에이전트와 통합되도록 설계되었습니다.Python 기반 도구: 에이전트/워크플로우 코드 생성에 사용되며 Bridgic과의 통합이 더 쉽습니다.의미적 불변성을 갖춘 스냅샷(Snapshot with Semantic Invariance): 접근성 트리(accessibility tree)와 특별히 설계된 참조(ref)-생성 알고리즘을 기반으로 페이지 스냅샷을 표현하며, 이로 인해 페이지 재로드 시 요소 참조가 변경되지 않도록 보장합니다.스킬(Skills): 안내된 탐색 및 코드 생성에 사용되며 대부분의 코딩 에이전트와 호환됩니다.스테일스 모드(Stealth Mode) (기본 활성화): 24개 이상의 JS/CDP 지문 인식 벡터를 다루는 모드 인지형 안티-디텍션 기능을 제공합니다. 공개된 봇 감지 벤치마크 스위트와 검증되었습니다 — 아래의 Anti-Detection을 참조합니다.영구 및 임시 세션(Persistent & Ephemeral Sessions): 기본적으로 영구 프로필($BRIDGIC_HOME/bridgic-browser/user_data/ 또는 기본값 ~/.bridgic/...)을 사용하거나, 프로필 없이 임시 세션을 위해 clear_user_data=True를 전달할 수 있습니다.중첩된 iframe 지원(Nested iframe Support): 다단계 중첩된 iframe 내의 DOM 요소 작업을 지원합니다. Bridgic Browser를 사용하는 가장 쉬운 방법은 코딩 에이전트나 AI 비서(예: Claude Code, Cursor, Codex 또는 OpenClaw)와 함께하는 것입니다. 이를 두 가지 방식으로 사용할 수 있습니다: 스킬(Skill)을 통해 또는 플러그인(Plugin)을 통해입니다. 두 경우 모두 Bridgic Browser가 자동으로 설치됩니다.방법 1: AI를 사용하여 브라우저를 직접 제어하고 실시간으로 작업을 완료합니다.

Karpathy.mp4

이 방법을 사용하려면 Bridgic Browser에서 제공하는 스킬을 설치해야 합니다.
npx skills add bitsky-tech/bridgic-browser --skill bridgic-browser
설치 후, 해당 스킬은 에이전트 디렉터리(예: Claude Code의 경우 일반적으로 .claude/skills/bridgic-browser/, Cursor의 경우 .agents/skills/bridgic-browser/)에 나타납니다.방법 2: 최소한의 토큰 사용으로 반복 가능한 브라우저 자동화 스크립트를 AI가 생성하도록 합니다.

이 방법을 사용하려면 AmphiLoop에서 제공하는 Plugin을 설치해야 합니다. 이는 자연어(natural language)를 사용하여 AI 에이전트를 구축하기 위한 완전히 새로운 방법론, 기술 스택 및 툴체인입니다.

pip install bridgic-browser

설치 후 Playwright 브라우저를 설치하세요:

playwright install chromium

bridgic-browser open --headed https://example.com
bridgic-browser snapshot
# 'f0201d1c'는 'Learn more' 링크의 ref 값입니다.
...

먼저, 빌드 도구를 만듭니다:

from bridgic.browser.session import Browser
from bridgic.browser.tools import BrowserToolSetBuilder, ToolCategory
# 브라우저 인스턴스를 생성합니다
...

두 번째로 (선택 사항), 이 도구 세트를 사용하는 Bridgic 에이전트를 만듭니다:

import os
from bridgic.llms.openai import OpenAILlm, OpenAIConfiguration
async def create_llm():
...

또한 기본 Browser API를 직접 호출하여 브라우저를 제어할 수 있습니다.

from bridgic.browser.session import Browser
browser = Browser(headless=False)
async def main():
...

bridgic-browser는 터미널에서 브라우저를 제어하기 위한 커맨드라인 인터페이스(CLI)를 제공하며 (15개 카테고리에 67개 도구 구성), 지속적인 데몬 프로세스가 브라우저 인스턴스를 유지합니다. 각 CLI 호출은 유닉스 도메인 소켓(Unix domain socket)을 통해 연결하고 즉시 종료됩니다.

브라우저 옵션은 다음 출처에서 자동으로 로드됩니다 (CLI 데몬 및 SDK Browser() 모두 해당). 우선순위 순서대로 적용되며, 나중에 설정된 값이 가장 높은 가중치를 갖습니다:

헤드 브라우저 참고 사항:
headless=false이고 스텔스 모드가 활성화된 경우, bridgic은 더 나은 안티-디텍션(anti-detection)을 위해 시스템 Chrome (설치된 경우)으로 자동 전환합니다 (Google OAuth는 Chrome for Testing에서 차단됨). 이를 재정의하려면 다음을 설정하세요:

channel

예: "chrome", "msedge", executable_path: 브라우저 바이너리에 대한 절대 경로

bridgic은 커스텀 Chromium 바이너리, 프록시 또는 CAPTCHA 솔버 없이도 대부분의 JS-fingerprint 기반 봇 탐지(bot detection)를 무력화하는 산업 등급의 스텔스 레이어(stealth layer)를 포함합니다. 이 전략은 **모드 인식적(mode-aware)**입니다. 헤드 모드(headed mode)는 실제 시스템 Chrome의 TLS 인증성을 활용하고, 헤드리스 모드(headless mode)에서는 더 완전한 JS-CDP 패치 스위트(JS-CDP patch suite)를 적용합니다. 아키텍처에 대한 자세한 내용은 docs/INTERNALS.md#mode-aware-stealth-design을 참조하세요.

마지막 검증일: 2026-05-12 (Playwright Chromium 143 / macOS의 시스템 Chrome 147).

JS + CDP 레이어에서 패치된 24개 이상의 탐지 벡터:

Anti-introspection foundation—Function.prototype.toString 인터셉션이 .toString() 프로브를 무력화합니다.
navigator—webdriver (삭제됨: Navigator.prototype에서 --disable-blink-features=AutomationControlled 시맨틱스에 맞추기 위해; 'webdriver' in navigator는 false를 반환)
, plugins & mimeTypes (네이티브 PluginArray / MimeTypeArray 프로토타입을 사용하며; item(i)가 Web IDL §3.2.4에 따라 uint32로 잘림)
, languages, deviceMemory, hardwareConcurrency, connection, permissions.query
window / document—chrome (runtime / csi / loadTimes), outerWidth/Height, hasFocus/hidden/visibilityState, Notification.permission
WebGL— UNMASKED_VENDOR / UNMASKED_RENDERER (SwiftShader / generic-vendor 누출 대체)UA / Sec-CH-UA(CDP를 통한 헤드리스 전용: Emulation.setUserAgentOverride) — navigator.userAgent, userAgentData.brands
Web Worker / SharedWorker / Service Worker(생성자 래핑 + importScripts를 통한 레이스 방지 주입) — deviceMemory에 대한 main↔worker 일관성

, languages,vendor,productSub,vendorSub , WebGL**CDP-attach 감지**—Debugger.setSkipAllPauses,console.* Error pre-stringify (blockserror.stack getter probes)**Anti devtools-detector**—console.table timing neutralization,devtoolsFormatters lockout,Function -constructordebugger`
strip

벡터별 구현 세부 사항:
docs/INTERNALS.md#stealth-js-init-script--patched-properties

.

JSON 소스는 모든 Browser
생성자 매개변수를 허용합니다:

{
"headless": false,
"proxy": {"server": "http://proxy:8080", "username": "u", "password": "p"},
...
}

# 일회성 환경 오버라이드
BRIDGIC_BROWSER_JSON='{"headless":false,"locale":"zh-CN"}' bridgic-browser open URL
# 일회성 임시 세션 (영구 프로필 없음)
...

기본적으로 모든 상태는 ~/.bridgic 아래에 저장됩니다. 여러 독립적인 데몬 인스턴스를 병렬로 실행하려면 BRIDGIC_HOME을 설정하세요. 각 인스턴스는 자체 소켓, 로그, 사용자 데이터 및 구성을 갖습니다:

# 인스턴스 1 (기본값)
bridgic-browser open https://site-a.com
# 인스턴스 2 (별도 홈)
...

동일 프로세스 내 SDK 다중 인스턴스 격리에는 Browser(user_data_dir=...)를 각 인스턴스에 사용하세요. 전체 프로세스 수준의 격리가 필요하면 서브프로세스를 생성하기 전에 BRIDGIC_HOME을 설정하세요. 자세한 내용은 skills/bridgic-browser/references/env-vars.md를 참조하세요.

하나의 브라우저 인스턴스에서 쿠키와 localStorage를 내보내 다른 인스턴스로 가져올 수 있습니다. 이는 여러 인스턴스에 걸쳐 로그인 세션을 공유하거나 나중에 실행할 인증 상태를 유지하는 데 유용합니다:

# 1. 인스턴스 A에서 웹사이트에 로그인
bridgic-browser open https://github.com --headed
# ... 브라우저에서 로그인 완료 ...
...

내보내진 JSON 파일에는 브라우저가 방문한 모든 오리진의 모든 쿠키(HttpOnly / Secure 포함)와 localStorage 항목이 포함되어 있습니다.

저장 상태 파일은 **크로스 모드 호환(cross-mode compatible)**합니다. 즉, 헤디드 세션에서 내보낸 것을 헤드리스 세션으로 가져오거나 (또는 그 반대) 로그인 세션이 유지됩니다. 이는 인증이 필요한 워크플로우를 자동화할 때 특히 유용합니다. 헤디드 모드에서는 CAPTCHA 및 2FA 프롬프트와 상호 작용할 수 있으므로 한 번만 로그인하고, 저장 상태를 내보낸 다음, 이를 헤드리스 자동화 실행에 재사용할 수 있습니다.

SDK 사용:

import asyncio
from bridgic.browser.session import Browser
async def main():
...

bridgic-browser는 새로운 브라우저를 시작하는 대신, Chrome DevTools Protocol을 통해 이미 실행 중인 Chrome/Chromium 인스턴스에 연결할 수 있습니다.

Chrome에서 원격 디버깅 엔드포인트가 노출되도록 시작하는 방법은 두 가지입니다.

옵션 A — Chrome 144 이상 인브라우저 UI (재실행 없음). 일상적인 Chrome 창에서 chrome://inspect/#remote-debugging을 열고, 대화 지침에 따라 들어오는 디버깅 연결을 허용합니다. Chrome은 로컬 엔드포인트를 열고 사용자 데이터 디렉토리 루트의 DevToolsActivePort 파일에 연결 정보를 작성합니다:

이 파일은 정확히 두 줄로 구성되어 있습니다. 포트와 브라우저 레벨 WebSocket 경로입니다:

9222
/devtools/browser/f8632266-41b6-4eb8-8239-d48a86bb44b1

bridgic의 --cdp auto는 이미 이러한 표준 프로필 디렉토리에서 DevToolsActivePort를 스캔하므로, 추가 인자 없이 즉시 연결할 수 있습니다:
bridgic-browser open https://example.com --cdp auto

세션이 활성화된 동안 Chrome은 *

macOS

/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
--remote-debugging-port=9222 --user-data-dir=/tmp/cdp-profile
...

그러면 --cdp로 연결합니다.

:

bridgic-browser open https://example.com --cdp 9222
bridgic-browser open https://example.com --cdp ws://localhost:9222/devtools/browser/...
bridgic-browser open https://example.com --cdp wss://cloud.example.com/chromium?token=...
...

탭 가시성 (Tab visibility): 사용자의 실행 중인 Chrome에 연결될 때, bridgic은 자신이 연 페이지만 볼 수 있습니다. 즉, 연결 시 생성된 완전히 새로운 탭, new-tab을 통해 생성된 모든 것, 그리고 단순한 왼쪽 클릭으로 <a target='_blank'> 링크를 클릭하거나 JavaScript의 window.open() 호출(Page.opener()를 통해 채택됨)으로 트리거된 팝업입니다. 사용자가 Cmd+click (macOS) / Ctrl+click (Win/Linux) / 가운데 클릭 / Cmd+T / 주소 표시줄로 여는 탭은 채택되지 않습니다. — Cmd/Ctrl/가운데 클릭 시 Chromium은 브라우저 프로세스 레벨에서 오프너를 지웁니다(

.auto_follow_popups=True
)
; set Browser(auto_follow_popups=False)

활성 포인터를 고정하려면, Browser(auto_follow_popups=False)를 설정하세요. 전체 채택 진실표는 docs/CDP_MODE.md#tab-ownership-in-cdp-mode에서 확인하세요.

닫기 동작: bridgic-browser close

이 명령어는 원격 브라우저와의 연결만 끊을 뿐, Chrome 프로세스를 종료하지 않습니다. 따라서 브라우저는 계속 실행되며 다시 연결할 수 있습니다.

사용 사례:

• 로그인 상태와 확장 프로그램이 유지된 기존 Chrome 세션 재사용
• 클라우드 브라우저 서비스(Browserless, Steel.dev 등)에 연결
• CDP 포트를 노출하는 Electron 앱 자동화

SDK 동등 명령어:

browser = Browser(cdp="ws://localhost:9222/devtools/browser/...")

자세한 내용은 모든 명령어에 -h 또는 --help를 사용하세요: