{"id":50564476,"url":"https://github.com/browser-use/browser-harness-js","last_synced_at":"2026-06-04T13:30:32.747Z","repository":{"id":352705117,"uuid":"1214564285","full_name":"browser-use/browser-harness-js","owner":"browser-use","description":"Self-healing browser harness that enables LLMs to complete any task","archived":false,"fork":false,"pushed_at":"2026-04-20T18:47:32.000Z","size":432,"stargazers_count":95,"open_issues_count":0,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T20:36:25.264Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/browser-use.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-18T18:44:16.000Z","updated_at":"2026-04-20T20:28:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/browser-use/browser-harness-js","commit_stats":null,"previous_names":["browser-use/browser-harness-js"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/browser-use/browser-harness-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browser-use%2Fbrowser-harness-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browser-use%2Fbrowser-harness-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browser-use%2Fbrowser-harness-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browser-use%2Fbrowser-harness-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/browser-use","download_url":"https://codeload.github.com/browser-use/browser-harness-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/browser-use%2Fbrowser-harness-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33907693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T13:30:32.658Z","updated_at":"2026-06-04T13:30:32.742Z","avatar_url":"https://github.com/browser-use.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://r2.browser-use.com/github/asbfgihsbfbaosfjla.png\" alt=\"Browser Harness\" width=\"100%\" /\u003e\n\n# Browser Harness JS ♞\n\nThe thinnest possible bridge from the LLM to Chrome. **No harness, no recipes, no rails** — just every CDP method as a typed JS call.\n\nOne persistent WebSocket, 56 domains, 652 typed wrappers, zero wrapping of what Chrome already does.\n\n```\n  ● agent: wants to click a button\n  │\n  ● no click() helper, no upload_file(), no goto()\n  │\n  ● agent writes the CDP call itself        await session.Input.dispatchMouseEvent({...})\n  │                                          await session.DOM.setFileInputFiles({...})\n  ✓ done — same pattern for all 652 methods\n```\n\n**The protocol is the API.** If Chrome can do it, you can call it.\n\n## Installation\n\n```bash\nnpx skills add https://github.com/browser-use/browser-harness-js --skill cdp\n```\n\nOr paste this into your agent — it'll install the skill, put the CLI on your PATH, and run a first task:\n\n```text\nRun `npx skills add https://github.com/browser-use/browser-harness-js --skill cdp`, then\nsymlink `browser-harness-js` into a directory on my PATH, then use the cdp skill to drive\nmy browser: look at all the tabs I have open, group them by topic, and screenshot the most\ninteresting one.\n```\n\n(The CLI auto-installs [`bun`](https://bun.sh) on first run if it's missing. Set `BROWSER_HARNESS_SKIP_BUN_INSTALL=1` to opt out.)\n\nIf Chrome asks you to tick a remote-debugging checkbox, do it — that's how the agent attaches:\n\n\u003cimg src=\"docs/setup-remote-debugging.png\" alt=\"Remote debugging setup\" width=\"520\" style=\"border-radius: 12px;\" /\u003e\n\nSee [interaction-skills/](interaction-skills/) for recipes on the mechanics that are not obvious from the CDP method list alone.\n\n## Files\n\n- `SKILL.md` — day-to-day usage; how to connect, pick a tab, call methods, persist state\n- `sdk/browser-harness-js` — tiny CLI that auto-spawns the server and forwards snippets\n- `sdk/repl.ts` — Bun HTTP server holding one persistent `Session`\n- `sdk/session.ts` — the `Session` class: transport, connect, target routing, events\n- `sdk/gen.ts` — codegen: reads `browser_protocol.json` + `js_protocol.json` → typed wrappers\n- `sdk/generated.ts` — every CDP method as `session.\u003cDomain\u003e.\u003cmethod\u003e(params)` (generated)\n\nNo helpers file. No `click()`, no `goto()`, no `upload_file()` — just the protocol, typed.\n\n## Why no pre-baked helpers?\n\nEvery helper is a lie about what CDP already gives you. `click(x, y)` hides `Input.dispatchMouseEvent` — which has 14 parameters the LLM might need (button, clickCount, modifiers, pointerType, force, tangentialPressure, …). A harness that exposes three of them quietly limits what the agent can do.\n\n- Types are the docs. `session.Page.navigate(` triggers autocomplete with the exact params — same JSDoc as the CDP reference.\n- No version drift. The SDK is regenerated from the upstream protocol JSON; new Chrome methods appear as soon as you swap the JSON.\n- No \"helper doesn't handle my case\" detours. If CDP can do it, the agent can call it — directly, typed, today.\n\nThe only \"helpers\" you'll find are things CDP itself is missing:\n- `listPageTargets()` — filters `chrome://` / `devtools://` out of `Target.getTargets`\n- `resolveWsUrl({wsUrl|port|profileDir})` — reads `DevToolsActivePort` for Chrome 144+\n- `session.use(targetId)` / `session.waitFor(method, pred, timeout)` — the two routing primitives you genuinely need\n\n## Contributing\n\nPRs welcome. The best way to help: **contribute a new interaction skill** under [interaction-skills/](interaction-skills/) when you figure out the CDP recipe for something non-obvious (a dropdown framework, a shadow-DOM trap, a network-wait pattern).\n\n- Keep recipes in **pure CDP** — `session.Domain.method(...)`, not wrapped helpers.\n- Lead with the shortest method call that works; add the workaround or trap afterwards.\n- Small and focused beats comprehensive. One mechanic per file.\n- Bug fixes, codegen improvements, and `session.ts` refinements are equally welcome.\n\n---\n\n[Bitter lesson](https://browser-use.com/posts/bitter-lesson-agent-frameworks) · [Skills](https://browser-use.com/posts/web-agents-that-actually-learn)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowser-use%2Fbrowser-harness-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrowser-use%2Fbrowser-harness-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrowser-use%2Fbrowser-harness-js/lists"}