- browser-use team mở mã Browser Harness JS — cầu nối mỏng nhất có thể từ LLM tới Chrome: 1 WebSocket, 56 domain, 652 method CDP đánh typed, không click()/goto() giả tạo.
- Triết lý: the protocol is the API.
TL;DR
Browser Harness JS là công cụ mã nguồn mở MIT của team browser-use, phơi toàn bộ Chrome DevTools Protocol (CDP) cho LLM dưới dạng 652 typed JavaScript method trải rộng 56 domain, chạy qua một WebSocket bền. Không click(), không goto(), không upload_file() — triết lý "the protocol is the API". Lý do: mỗi helper đều giấu bớt tham số CDP (ví dụ Input.dispatchMouseEvent có 14 tham số, helper giữ lại 3 là giết đi sự linh hoạt của agent).
What's new
SDK được auto-generate từ protocol JSON upstream của Chrome (browser_protocol.json + js_protocol.json). Chrome ra method mới? Swap JSON, typed wrapper xuất hiện ngay — zero version drift. Không còn trò "framework chưa kịp thêm method" như Playwright/Puppeteer.
Cài đặt đúng một dòng cho agent:
npx skills add ... --skill cdpSkill drop vào ~/.claude/skills/cdp (Claude Code) hoặc ~/.cursor/skills/cdp (Cursor). CLI tự cài Bun lần chạy đầu (opt-out bằng BROWSER_HARNESS_SKIP_BUN_INSTALL=1). SKILL.md dạy agent cách connect, chọn tab, gọi method, persist state giữa các call.
Why it matters
Browser automation cho AI agent lâu nay bị thống trị bởi Selenium, Playwright, Puppeteer — đều là tầng abstraction dày chồng lên CDP. Vấn đề: helper luôn nói dối về những gì CDP đã có. click(x, y) giấu 14 tham số của Input.dispatchMouseEvent (button, clickCount, modifiers, pointerType, force, tangentialPressure, …). Helper giữ lại 3 là agent mất quyền dùng 11 tham số còn lại. Nếu framework tác giả không nghĩ tới case của bạn — agent kẹt "framework gap", phải đợi human dev vá.
Browser Harness JS lật ngược quan hệ đó: nếu Chrome làm được, agent gọi được — trực tiếp, typed, ngay hôm nay. Types chính là docs; session.Page.navigate( bật autocomplete với JSDoc khớp đúng CDP reference.
Technical facts
| Item | Value |
|---|---|
| Typed JS method wrappers | 652 |
| CDP domains | 56 |
| Transport | 1 persistent WebSocket |
Params exposed cho dispatchMouseEvent | 14 |
| REPL runtime | Bun-native HTTP server (port 9876) |
| License | MIT, open-source |
| Python sibling | ~592 LOC (browser-harness) |
Core files trong SDK:
sdk/browser-harness-js— Bash CLI, auto-spawn server + forward snippetsdk/repl.ts— Bun HTTP server giữ 1 Session duy nhấtsdk/session.ts— Session class: transport, connect, target routing, eventssdk/gen.ts— codegen đọcbrowser_protocol.json+js_protocol.jsonsdk/generated.ts— mọisession.<Domain>.<method>(params)
Các helper còn lại trong project chỉ dành cho những gì CDP thiếu: listPageTargets() lọc bỏ chrome:// và devtools://, resolveWsUrl() đọc DevToolsActivePort trên Chrome 144+, session.use(targetId) và session.waitFor() — hai primitive routing thật sự cần.
Comparison
| Tool | Best for | Key differentiator |
|---|---|---|
| Browser Harness JS | Agentic Chrome control qua raw CDP | 652 typed wrappers, 1 WebSocket, no helper layer |
| Playwright | E2E test cross-browser | Auto-waits, selectors, Chromium/FF/WebKit |
| Puppeteer | Chrome scripting / scraping | API mature, đơn giản hơn raw CDP |
| Raw CDP | Tầng protocol thấp nhất | Max control nhưng tự wire hết |
Một lựa chọn thiết kế đáng chú ý: coordinate-click qua Input.dispatchMouseEvent với toạ độ viewport tuyệt đối, thay vì DOM selector click. Toạ độ đi thẳng qua iframe, shadow DOM, cross-origin ở tầng compositor — đúng cách chuột người dùng thật hoạt động. Đánh đổi: mất selector precision, nhưng reach universal. Với LLM có thị giác, pick toạ độ không khó.
Use cases
- AI coding agent (Claude Code, Codex, Cursor) điều khiển browser thật cho GitHub ops, form filling, scraping, data entry.
- Headless deploy dùng remote browser trong sub-agent.
- Shadow DOM, OOPIF, drag-and-drop, file upload/download, print-as-PDF, dialog — những thứ helper thường chết — đều làm được vì agent gọi thẳng CDP.
- Thư viện skill: 50+ markdown guide cho site cụ thể (Amazon, GitHub, LinkedIn, Spotify, Steam, Zillow…) + 16 interaction-skill guide (tabs, iframes, cookies, screenshot, upload, download…). Agent đọc guide on-demand thay vì import logic hardcoded.
Limitations & pricing
- Chrome-only. Không Firefox, không WebKit — vì bind thẳng CDP.
- Learning curve dốc — agent/dev phải đọc protocol docs, hiểu target routing.
- Verbose hơn Playwright — thao tác đơn giản tốn nhiều dòng vì refuse hide protocol.
- Không có auto-waits, retry, assertion built-in. Tự timing, tự sync.
- Không phải test runner.
- Cần bật remote-debugging Chrome; lần đầu user phải tick confirm dialog.
- Giá: 0đ. MIT, open-source.
What's next
Browser Harness JS là bản JS của triết lý đã ship ở Python (browser-harness, ~592 LOC, cơ chế "self-healing": agent tự viết function thiếu vào helpers.py giữa task). Roadmap mở: cộng đồng đóng góp file dưới interaction-skills/, mỗi file một cơ chế CDP không hiển nhiên (dropdown framework, shadow-DOM trap, network-wait pattern). Vì codegen từ protocol JSON upstream, dự án không có version-drift — Chrome ra capability mới là agent xài được ngay.
Nguồn: github.com/browser-use/browser-harness-js, Show HN, ToolHunter review, Jimmy Song deep dive.
