caveman-browse

A token-efficient alternative to Playwright MCP for coding agents. One Go binary that attaches to the Chrome you already run, reads the real accessibility tree, compresses it, and gives your agent four tools that cost 297 tokens of catalog — versus 3,422 for Playwright MCP (0.0.79) and 4,507 for Chrome DevTools MCP (1.7.0), measured live 2026-08-14.

Numbers are inferred token counts measured with an offline o200k_base counter on pinned fixtures — see BENCHMARK.md for methodology, reproduction commands, and the cases where Playwright's bare ARIA text is smaller (tiny pages; we print those too).

Full-task head-to-head (same headless agent, same task, server swapped; provider-reported session tokens; 2026-08-14 pilot, n=1/cell, all arms passed): finding one row in a 200-row table cost 150k total input tokens through caveman-browse vs 203k (Playwright MCP) / 223k (Chrome DevTools MCP); counting matching rows 168k vs 358k / 223k. On the action-heavy checkout task caveman-browse lost (668k vs 362k / 312k) — its settle-proof loop re-snapshots after every action instead of trusting dispatch. Full tables, causes, and claim boundaries: benchmarks/agentloop/RESULTS.md, benchmarks/toolcatalog/RESULTS.md, benchmarks/snapshot/RESULTS.md.

Install

Claude Code (plugin — server + usage skill):

/plugin marketplace add JuliusBrussee/caveman-browse
/plugin install caveman-browse@caveman-browse

Claude Code (MCP only):

claude mcp add caveman-browse -- npx -y caveman-browse

Cursor / any MCP host (.mcp.json / mcp.json):

{ "mcpServers": { "caveman-browse": { "command": "npx", "args": ["-y", "caveman-browse"] } } }

Gemini CLI:

gemini extensions install https://github.com/JuliusBrussee/caveman-browse

The npm shim downloads a signature-verified prebuilt binary on first run. No Node runtime is involved after launch; no Chromium is bundled — it drives your installed Chrome with a dedicated automation profile.

The four tools

• browser_snapshot(url?, wait?, query?, interactive?) — compact accessibility tree with [uid] action handles plus one accounting line (caveman before=… after=… ratio=… basis=inferred handle=ccr_…). query keeps the ≤12 best-matching nodes plus ancestors — the token-efficient path on large pages. interactive: true keeps only actionable nodes.
• browser_act(action, uid, text?, option?) — click, type, select, scroll, wait. Returns settled:false until a focused re-snapshot proves the app updated; the driver never claims success it hasn't seen.
• browser_eval(expression) — JS escape hatch.
• browser_recover(recovery_handle, query?) — the byte-exact original Accessibility.getFullAXTree payload behind any snapshot (CCR-backed), or BM25-narrowed sections with a query. Compression here is never a one-way door.

Direct CLI

npx caveman-browse snapshot http://127.0.0.1:3000
npx caveman-browse snapshot http://127.0.0.1:3000 "save settings"   # focused
npx caveman-browse snapshot -i http://127.0.0.1:3000                # actionable only
npx caveman-browse act <uid> click
npx caveman-browse recover <handle>
npx caveman-browse close

Direct commands share one detached, isolated Chrome until close. Navigation allows http(s), about:blank, and bounded data:text/html; file:, javascript:, and privileged schemes fail closed with cave_snake_code errors.

Honesty model

• Every savings figure is inferred (offline BPE count), never provider usage, never billing, never re-projected to a period.
• Lossy snapshots are emitted only when the byte-exact original is stored for recovery (CCR-or-passthrough).
• Unknown roles, uids, or CDP responses fail closed — no fabricated handles, no claimed success without settlement proof.
• Scope: same-origin pages with predictable controls. Cross-origin iframes appear as leaves; OOPIFs, dialogs, downloads, and arbitrary-open-web actionability are out of scope (see the claim boundary in BENCHMARK.md).

Build from source

go build ./cmd/caveman-browse
CAVEMAN_BROWSE_CHROME="/path/to/Chrome" go test -tags=integration ./...

License

Source and binaries ship under Business Source License 1.1 (source-available; first-party self-hosted production permitted; third-party hosted/managed/embedded use requires a commercial license). Third-party notices: NOTICE. Part of the Caveman efficiency stack; the a11y compressor and CCR live in the Caveman engine.