BrowserCode: 정해진 동작 API 대신 자바스크립트를 작성해 실제 Chrome을 조작하는 브라우저 에이전트

9bow · 8월 26, 2026, 12:30오전

BrowserCode 소개

웹을 다루는 AI 에이전트는 대개 정해진 동작 목록을 도구로 받습니다. 클릭, 입력, 스크롤, 요소 읽기 정도가 노출되고, 에이전트는 그 목록 안에서만 페이지를 다룹니다. 이 구조는 예상한 모양의 페이지에서는 잘 동작하지만, 무한 스크롤 목록에서 항목을 모두 모으거나 그림자 DOM(Shadow DOM) 안의 요소를 다루는 것처럼 목록 밖의 상황이 오면 막힙니다. 사이트마다 구조가 다르니 새 사이트를 만날 때마다 같은 벽에 부딪히고, 결국 도구 목록을 늘리는 쪽으로 대응하게 됩니다.

이번에 소개할 BrowserCode는 그 목록을 늘리는 대신 브라우저 조작을 코드 작성 문제로 바꾸는 방향을 택한 터미널 에이전트입니다. BrowserCode는 에이전트에게 자바스크립트를 실행할 통로 하나만 주고, 에이전트가 페이지를 보고 필요한 코드를 그때그때 작성합니다. 개발사인 Browser Use 는 이 설계의 근거를 "Browser ability and code-writing ability are deeply connected" 라는 문장으로 설명하며, 브라우저를 다루는 능력과 코드를 쓰는 능력이 같은 능력이라고 봅니다.

BrowserCode는 터미널에서 도는 오픈소스 도구이고, 같은 에이전트를 계정 기반으로 대신 실행해 주는 Browser Use Cloud 가 함께 있습니다. 저장소를 클론해 직접 실행하는 쪽은 무료이며, 클라우드 쪽은 API 키를 발급받아 쓰는 유료 서비스입니다. 저장소 이름과 실행 명령은 프로젝트 이름과 달라서, 저장소는 browsercode 이고 설치 후 입력하는 명령은 bcode 입니다. 아래 명령에서는 그 이름을 그대로 씁니다.

BrowserCode의 핵심 원시 기능: browser_execute

BrowserCode가 OpenCode ( Opencode: 다양한 LLM을 사용할 수 있는, 터미널 기반의 오픈소스 AI 코딩 에이전트) 에 더한 것은 원시 기능(Primitive) 하나입니다. Browser Use 가 정리한 동작은 다음과 같습니다:

browser_execute(code)
  -> runs JavaScript in-process
  -> talks to Chrome through the DevTools Protocol
  -> keeps the browser session alive across calls
  -> returns logs, values, and screenshots to the agent

정리하면 에이전트가 넘긴 자바스크립트를 프로세스 안에서 실행하고, Chrome DevTools Protocol(CDP) 로 Chrome 에 직접 말을 걸며, 호출 사이에 브라우저 세션을 살려 두고, 실행 결과로 로그와 값과 스크린샷을 함께 돌려줍니다. 세션이 유지되기 때문에 에이전트는 페이지를 한 번 열어 둔 상태에서 코드를 여러 번 나눠 실행하며 탐색할 수 있습니다.

한 번 통한 코드는 버려지지 않습니다. 에이전트가 작성한 재사용 가능한 브라우저 스크립트는 .bcode/agent-workspace/ 에 파일로 남아, 같은 작업을 다시 할 때 그대로 불러 쓸 수 있습니다.

또한 구성은 포크와 이식의 조합입니다. BrowserCode 는 OpenCode 를 포크한 코드 위에, Browser Harness ( Browser Harness: LLM이 직접 Chrome을 제어하며 부족한 기능을 스스로 구현하는 자기 치유형 브라우저 자동화 프레임워크) 의 타입스크립트 이식본을 저장소 안에 함께 넣어 두었습니다. 그래서 프로젝트는 기여를 받을 때도 브라우저 자동화 쪽 변경은 Browser Harness 저장소로, 코딩 에이전트 본체 쪽 변경은 OpenCode 저장소로 보내라고 안내합니다. 다만 이름이 비슷해 오해하기 쉬운 지점이 하나 있어서, 프로젝트는 "BrowserCode is not built by the OpenCode team and is not affiliated with OpenCode in any way" 라고 관계를 분명히 밝혀 두었습니다.

BU Bench로 측정한 모델별 성능

BrowserCode 는 API 키로 접근할 수 있는 모델과 OpenCode 가 지원하는 모든 공급자를 쓸 수 있습니다. 그래서 어떤 모델을 붙이느냐가 결과를 크게 가릅니다. Browser Use 가 자체 벤치마크인 BU Bench 로 측정해 공개한 값을 보면 모델별 편차가 뚜렷합니다:

가장 높은 점수는 claude opus-4-8 의 89.5% 이고, claude fable-5 와 claude opus-5 가 87.0%, grok 4.5 가 86.3% 로 이어집니다. 공개 가중치 모델 중에서는 kimi k3 가 86.0%, glm 5.2 가 84.0% 로 상위권에 들어 있습니다. 하단은 gemini 3-flash 66.2%, gemini 3.5-flash-lite 61.0% 입니다.

이 그래프에서 특히 눈여겨볼 값은 gpt-5.6-luna 가 두 번 등장한다는 점입니다. 추론 강도(Reasoning Effort)를 xhigh 로 올린 쪽은 82.0% 인데 기본값 쪽은 72.4% 로, 같은 모델에서 9.6 포인트가 벌어집니다. 따라서 모델을 바꾸지 않고 추론 강도만 조정해도 모델 간 차이만큼 결과가 달라집니다.

Browser Use 는 이 측정 결과를 바탕으로 용도별 추천 모델도 정리해 두었습니다:

성능 우선은 claude-opus-4-8 (점수 89.5%, 시간당 25.8 작업, 1달러당 1.1 작업), 공개 가중치 중에서는 kimi-k3 (86.0%, 시간당 6.3 작업, 1달러당 1.3 작업), 비용 대비 효율은 xhigh 로 설정한 gpt-5.6-luna (82.0%, 시간당 25.6 작업, 1달러당 26.6 작업)입니다. 1달러당 처리 작업 수에서 luna 가 opus 의 24배에 이르는 것이 이 추천의 근거입니다. 차트는 구독 사용 가능 여부도 함께 표시하는데, opus-4-8 은 Claude Code 구독으로 쓸 수 없고 luna 는 Codex 구독을, kimi-k3 은 Kimi Coding 구독을 쓸 수 있다고 적혀 있습니다. 이 값들은 모두 개발사인 Browser Use 가 자체 벤치마크로 측정해 공개한 수치입니다.

성능 주장 자체도 개발사의 표현으로 읽는 것이 정확합니다. Browser Use 는 "BrowserCode outperforms every browser agent we have tested it against" 라고 적어 두었는데, 비교 대상 목록과 각 대상의 점수는 공개하지 않았습니다.

기존 브라우저 자동화 도구와 다른 점

PyTorchKR 에도 브라우저를 다루는 도구가 여러 번 소개됐고, 각자 해결하려는 지점이 다릅니다. Moli와 Obscura는 브라우저 자체를 가볍게 만드는 쪽이고, Stagehand는 자동화 프레임워크에 자연어 지시를 얹는 쪽입니다. BrowserCode 는 브라우저를 새로 만들지도, 동작 API 를 다듬지도 않고, 실제 Chrome 을 그대로 쓰면서 그 위에서 에이전트가 코드를 쓰게 합니다.

같은 개발사의 Browser Harness 와의 관계는 경쟁이 아니라 포함입니다. Browser Harness 가 Chrome 을 제어하는 계층이고, BrowserCode 는 그 계층을 타입스크립트로 이식해 코딩 에이전트 안에 넣은 결과물입니다.

BrowserCode 설치와 사용법

설치는 한 줄이고, bash 를 지원하는 터미널에서 실행합니다:

curl -fsSL https://bcode.sh/install | bash

설치가 끝나면 bcode 로 대화형 화면(TUI)을 열거나, bcode run 으로 지시 한 줄만 넘겨 비대화형으로 실행할 수 있습니다:

bcode
bcode run "On Google flights return all flight details from New York to SF tomorrow"

모델 연결은 TUI 안에서 /connect 를 입력하거나, 공급자 API 키를 환경 변수로 두면 됩니다. 클라우드 쪽에서 같은 에이전트를 실행하려면 HTTP 요청 한 번으로도 됩니다:

curl -X POST https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Your task"}'

소스에서 직접 실행하려면 Bun 이 필요합니다:

git clone https://github.com/browser-use/browsercode.git
cd browsercode
bun install
bun run --cwd packages/opencode dev

BrowserCode에 브라우저를 붙이는 세 가지 방법

브라우저를 어떻게 붙일지는 별도 설정이 아니라 지시문으로 정해집니다. 프로젝트는 세 가지 경우를 예시로 들고 있습니다. 첫째는 지금 열려 있는 내 브라우저의 탭을 이어받는 방식이고, 둘째는 에이전트가 자기 브라우저 프로필을 새로 만들어 그 안에서만 작업하는 방식이며, 셋째는 원격 브라우저를 열어 그쪽에서 실행하는 방식입니다. Browser Use 가 예시로 든 지시문은 다음과 같습니다:

Connect to my current tab on amazon.com and find deals for 64GB DDR5 RAM, return URLs
Make a new browser profile and QA test http://localhost:3000, fix bugs and open a PR
Open a remote browser and extract every item sold on mcdonalds.com in SF

세 번째 방식이 Browser Use Cloud 를 쓰는 경로입니다. 클라우드 브라우저는 개수 제한 없이 무료로 쓸 수 있지만 동시 세션은 3개로 묶여 있고, 스텔스 접속과 캡차 처리, 프록시가 함께 제공됩니다. 환경 변수에 BROWSER_USE_API_KEY 를 두면 연결되며, 프로젝트는 에이전트가 스스로 가입까지 할 수 있다고 적어 두었습니다.

BrowserCode는 누구에게 유용한가

사이트 구조가 자주 바뀌거나 동작 API 로는 다루기 어려운 페이지를 자동화해야 하는 개발자에게 BrowserCode 는 시도해 볼 값어치가 있습니다. 한 번 통한 코드가 .bcode/agent-workspace/ 에 남아 다음 실행에서 재사용되므로, 같은 사이트를 반복해서 다룰수록 유리해지는 구조입니다. 모델을 고를 수 있다는 점도 실무에서는 큰 차이인데, 위 벤치마크대로 비용 대비 효율만 보면 상위 모델을 쓰지 않고도 82.0% 선을 확보할 수 있습니다.

다만 도입 전에 확인할 것이 세 가지 있습니다. 첫째, BrowserCode 는 익명 사용 추적(Telemetry) 정보를 기본으로 전송하며, 끄려면 환경 변수에 DO_NOT_TRACK=1 을 설정해야 합니다. 둘째, 원격 브라우저 경로는 Browser Use Cloud 계정에 묶여 있으므로 외부 서비스에 트래픽을 보낼 수 없는 환경에서는 로컬 브라우저 경로만 쓸 수 있습니다. 셋째, 에이전트가 임의의 자바스크립트를 실행한다는 것이 이 프로젝트의 설계인 만큼, 로그인된 개인 브라우저의 탭을 그대로 이어받는 사용 방식은 그 위험을 감안해 판단해야 합니다.

BrowserCode의 라이선스

BrowserCode 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!