chrome-agent
PyPI version
PyPI downloads
Python versions
License
Chrome DevTools Protocol을 통해 AI 코딩 에이전트가 Chrome 브라우저를 관찰하고 상호 작용할 수 있는 능력을 제공하는 CLI 도구입니다.
<h3 align="center">다음 엔지니어들이 사용합니다</h3>
<p align="center">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/microsoft.svg" alt="Microsoft" height="28">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/johns-hopkins-university.svg" alt="Johns Hopkins University" height="30">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/bosch.svg" alt="Bosch" height="28">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/texas-instruments.svg" alt="Texas Instruments" height="30">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/deutsche-telekom.svg" alt="Deutsche Telekom" height="28">
<br><br>
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/texas-am-university.svg" alt="Texas A&M University" height="30">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/red-hat.svg" alt="Red Hat" height="28">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/sysco.svg" alt="Sysco" height="28">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/databricks.svg" alt="Databricks" height="28">
</p>
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/grainger.svg" alt="Grainger" height="28"><br><br>
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/posthog.svg" alt="PostHog" height="28">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/nextiva.svg" alt="Nextiva" height="28">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/jusbrasil.svg" alt="Jusbrasil" height="28">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/parcellab.svg" alt="parcelLab" height="28">
<img src="https://raw.githubusercontent.com/captivus/chrome-agent/main/docs/logos/zuru-tech.svg" alt="ZURU Tech" height="28">
</p>
이것이 존재하는 이유 (Why this exists)
AI 코딩 에이전트는 브라우저를 보고 상호작용해야 합니다. 이는 코드 테스트, 자동화 디버깅, 페이지 상태 검사 등을 위해서입니다. 표준 접근 방식(브라우저 MCP 도구)은 프로토콜 협상과 상세한 응답 형식을 사용하는 영속적인 서버를 이용합니다. chrome-agent는 다른 접근 방식을 취합니다: 추상화 계층 없이 Chrome의 DevTools Protocol에 직접 액세스하는 것입니다.
이는 전체 CDP(Chrome DevTools Protocol) 프로토콜 접근을 의미합니다. 즉, Chrome이 노출하는 모든 명령어, 모든 이벤트, 모든 도메인입니다. 이는 선별된 기능 세트가 아니라 완전한 프로토콜 자체입니다. 에이전트는 DevTools가 하는 방식과 동일하게 CDP 원시 요소(primitives)로부터 상호작용을 구성합니다.
자체 버전이 아닌 실행 중인 브라우저 추적 (Tracks the running browser, not its own version)
예를 들어, CrashReportContext와 WebMCP 도메인은 나중에 Chrome에서 출시된 CDP에 추가되었지만, 이전 버전의 chrome-agent 타입 바인딩에는 이 두 도메인이 모두 없습니다. 그럼에도 불구하고 하나의 메서드는 CLI(Command Line Interface)를 통해 정상적인 결과를 반환하며, chrome-agent 자체는 변경되지 않습니다:
chrome-agent myproject-01 CrashReportContext.getEntries
단일 시점의 아티팩트는 타입이 지정된 Python 클래스입니다(Python API 참조) -- 이는 생성 시점에 스키마를 스냅샷하는 선택적 편의 계층입니다. 이들은 접근을 막지 않습니다: CDPClient.send(method=..., params=...)는 어떤 메서드에든 도달할 수 있습니다. 또한 help는 실행 중인 브라우저에서 프로토콜 스키마를 실시간으로 읽어오므로, 문서가 항상 사용자의 Chrome만큼 최신 상태입니다.
설치 (Installation)
uv tool install chrome-agent
또는 프로젝트에 추가합니다:
시스템에 Google Chrome 또는 Chromium이 설치되어 있어야 합니다. 런타임 종속성은 websockets이며, 저장된 세션을 암호화하기 위해 cryptography와 keyring이 추가로 필요합니다. Playwright도 없고, 브라우저 다운로드도 없습니다.
빠른 시작 (Quick Start)
인스턴스 패턴 (Instance Patterns)
인스턴스 이름이 허용되는 모든 곳에서, 대신 글롭(glob)을 사용할 수 있습니다 -- *, ?, [abc]와 같이 등록된 이름과 대소문자를 구분하여 일치시킵니다.
chrome-agent stop 'myproject-*'
chrome-agent status 'myproject-*'
chrome-agent 'myproject-0[2]' Page.navigate '{"url": "https://example.com""}'
stop과 status는 매칭되는 모든 항목에 대해 작동합니다. 단일 브라우저 명령어(예: attach, help, 일회성 CDP 호출)는 정확히 하나의 인스턴스와 일치하는 패턴을 해석하며, 그렇지 않은 경우 하나를 선택하는 대신 후보 목록과 함께 오류를 반환합니다. 아무것도 일치하지 않는 패턴은 조용한 무효화(no-op)가 아니라 오류입니다.
패턴을 따옴표로 묶으세요. 셸은 chrome-agent가 보기 전에 따옴표로 묶지 않은 글롭을 확장하며, 작업 디렉터리에 아무것도 일치하지 않으면 zsh는 명령 자체를 중단합니다 (zsh: no matches found: myproject-*).
리터럴 이름은 절대 패턴으로 취급되지 않기 때문에, chrome-agent stop myproject-01이 myproject-02를 포함하여 처리할 수 없습니다. stop --target은 하나의 탭을 닫기 때문에, 여러 인스턴스를 일치시키는 패턴과 결합하는 것이 거부됩니다.
탭 완성 (Tab Completion)
zsh 전용입니다. 현재로서는요. 설치 방법은 두 가지가 있습니다. 하나를 선택하세요.
.zshrc에서 소싱(Sourced from .zshrc) -- 한 줄로 작성되며 어디서든 작동하고, 셸 시작 시 하나의 서브프로세스 비용(약 60ms)이 발생합니다. 반드시 compinit 후에 와야 합니다:
source <(chrome-agent completions zsh)
파일로 설치하는 방법 (Installed as a file) -- 시작 비용은 없지만, 디렉토리가 compinit이 실행되기 전에 $fpath에 있어야 합니다. 이 단계는 놓치기 쉽습니다:
mkdir -p ~/.config/zsh/completions
chrome-agent completions zsh > ~/.config/zsh/completions/_chrome-agent
fpath=(~/.config/zsh/completions $fpath)
autoload -Uz compinit && compinit
두 번째 블록은 이 순서대로 .zshrc에 넣어야 합니다. 만약 디렉토리가 $fpath에 없다면, 파일이 단순히 읽히지 않아 Tab 키가 아무것도 하지 않습니다. 오류 메시지도 없습니다.
어느 방법을 사용하든, 새 셸을 열어 확인해 보세요:
서브커맨드와 실행 중인 인스턴스가 각각 설명과 함께 표시되어야 합니다. 아무것도 나타나지 않으면, echo $_comps[chrome-agent]가 _chrome-agent를 출력해야 합니다. 빈 결과는 완성(completion)이 등록되지 않았음을 의미합니다.
생성된 파일은 완성 로직의 스냅샷이므로, chrome-agent를 업그레이드한 후에는 다시 생성해야 합니다. (*후보군(candidates)*은 항상 실시간으로 읽어오지만, 함수 자체는 그렇지 않습니다). .zshrc에서 소싱하는 방법은 이를 완전히 방지합니다.
서브커맨드, 플래그, 실시간 인스턴스 이름, 그리고 CDP 메서드 및 이벤트 이름을 완성합니다:
chrome-agent stop reader<TAB> -> ensorcell-reader-01, described by port and tab count
chrome-agent taleb-01 Page.nav<TAB> -> Page.navigate
chrome-agent attach taleb-01 +Page.load<TAB> -> +Page.loadEventFired
인스턴스 이름은 입력하는 동안 레지스트리에서 읽어오므로, 설치 시점에 포함된 목록이 아니라 실제로 등록된 것이 됩니다. 메서드와 이벤트는 chrome-agent에 배포되는 스냅샷이 아니라 실행 중인 브라우저 자체의 /json/protocol에서 가져옵니다. 이 프로토콜은 브라우저 버전에 따라 디스크에 캐싱되므로, Chrome 업그레이드가 발생하면 무효화됩니다. 실행 중인 브라우저가 없으면 후보군을 얻을 수 없습니다.
프로토콜 캐시는 $XDG_CACHE_HOME/chrome-agent (기본값 ~/.cache/chrome-agent) 아래에 브라우저 버전별로 하나의 파일 형태로 존재합니다. 이를 삭제하는 것은 안전하며, 재요청 시 7ms의 비용이 발생합니다.
두 가지 채널 (Two Channels)
chrome-agent는 브라우저 상호 작용을 위해 두 가지 채널 패턴을 사용합니다:
일회성 모드 (One-shot mode, 명령어)
단일 CDP 명령을 전송합니다. 연결하고, 전송하고, JSON 응답을 출력한 후, 연결을 해제합니다.
chrome-agent <instance> Domain.method '{"param": "value"}'
스팟 체크, 스크린샷, 빠른 질의에 적합합니다. 호출당 약 50~80ms가 소요됩니다. 단일 인스턴스만 실행 중인 경우, 인스턴스 이름을 생략할 수 있습니다.
연결 모드 (Attach mode, 이벤트)
격리된 이벤트 구독을 가진 영구적인 연결입니다. 이벤트를 JSON 라인 형태로 표준 출력(stdout)에 스트리밍합니다.
chrome-agent attach <instance> +Page.loadEventFired +Network.requestWillBeSent
일회성 명령을 보내는 동안 백그라운드에서 실행할 수 있습니다:
chrome-agent attach myproject-01 +Page.loadEventFired +Network.requestWillBeSent > /tmp/events.jsonl &
...
연결 세션은 목적을 다하면 스스로 종료됩니다 — 인스턴스가 레지스트리에서 제거되거나, 브라우저가 사라지거나 더 이상 연결할 수 없게 되면 그러합니다. 따라서 백그라운드에서 관찰하는 옵저는 감시하던 대상이 사라진 후 무한정 남아있지 않습니다. 또한, 이벤트가 도착하지 않아 유휴 상태일 때도 SIGTERM/SIGINT에 의해 깔끔하게 종료됩니다 (CDP 세션 연결 해제). 일시적인 레지스트리 읽기 오류나 CDP 포트의 문제는 처리되지 않고 지나갑니다.
운영 명령어 (Operational Commands)
chrome-agent launch [--headless] [--fingerprint PATH] [--port PORT] [--no-window-border]
chrome-agent status [<instance|glob>]
chrome-agent attach <instance|glob> [+Event ...] [--target SPEC | --target-id ID | --target-index N | --url SUBSTRING]
...
| 명령어 | 설명 |
|---|
launch | 크롬을 찾아 CDP가 활성화된 상태로 실행합니다. 포트를 자동으로 할당하고 현재 디렉터리에서 인스턴스 이름을 지정합니다. |
인스턴스는 /tmp/chrome-agent/registry.json에 있는 레지스트리에서 추적됩니다. GUI(헤드) 브라우저의 인스턴스는 창이 닫힐 때 자동으로 레지스트리에서 제거됩니다 (세션 디렉터리도 정리됨). 따라서 status는 실제로 실행 중인 상태를 반영합니다.
활성 상태(Liveness)는 단순한 PID 존재 여부 확인이 아니라 프로세스 식별자 및 포트 할당을 통해 결정됩니다. 기록된 PID는 실행 사용자에게 속하고 시작 시간이 launch 시점에 기록된 것과 일치하는 살아있는 프로세스인 경우에만 유효하며 (따라서 재활용되거나 네임스페이스 로컬의 PID가 브라우저로 위장할 수 없습니다), 리스닝 중인 CDP 포트는 이 인스턴스의 프로필 디렉터리를 가진 해당 포트를 주장하는 프로세스가 발견될 때만 유효합니다. 따라서 wrapper/snap 런처를 통해 시작된 브라우저는 여전히 올바르게 보고되며, 다른 브라우저가 이미 점유한 포트가 이 인스턴스로 오인되지 않습니다.
일시적인 연결 끊김은 살아있는 인스턴스를 종료시키지 않습니다. 호스트의 일시 중단/재개는 슈퍼바이저의 CDP 연결을 끊지만 크롬은 계속 실행되므로, 슈퍼바이저는 재연결하여 감독을 유지합니다. 인스턴스의 종료(retirement)는 CDP 포트가 리스닝을 멈출 때만 발생합니다. cleanup은 남아있는 모든 항목(헤드리스 인스턴스 또는 갑자기 종료된 브라우저)을 제거합니다.
알아두면 좋은 두 가지 결과가 있습니다. PID 네임스페이스(PID-namespaced) 샌드박스 내부에서 실행하는 것(컨테이너, bubblewrap, 일부 에이전트 CLI 샌드박스 등)은 해당 샌드박스의 로컬 PID를 공유 레지스트리에 기록합니다. 이로 인해 무효화된 브라우저가 사라진 후에는 식별 검사(identity check)가 해당 항목을 오래된(stale) 것으로 인식하며, 별칭이 지정된 호스트 PID를 영원히 활성 브라우저로 취급하지 않습니다. stop은 행동하기 전에 대상을 확인합니다: 다른 브라우저를 서비스하는 포트로 Browser.close를 보내지 않으며 (대신 인스턴스의 자체 검증된 프로세스를 종료하거나 오래된 항목을 정리할 뿐입니다), SIGTERM 폴백(fallback)은 항상 해당 인스턴스의 자체 브라우저 프로세스로 확인된 PID에서만 발생합니다.
세션 저장 및 복원
실행된 브라우저의 프로필은 /tmp/chrome-agent/ 아래에 존재하며, 브라우저가 닫힐 때 삭제됩니다. 또한 대부분의 Linux 시스템은 부팅 시 어차피 /tmp를 비우기 때문에, 로그인 정보, 쿠키 및 열린 탭은 저장하지 않으면 재시작 후에도 유지되지 않습니다:
chrome-agent save --all --stop
chrome-agent restore --all