Skip to main content

Caveman Browse

caveman-browse is a local browser-interaction MCP server. It attaches to Chrome, reads Accessibility.getFullAXTree, compresses the AX payload through the Caveman engine's a11y compressor, and exposes four tools:

  • browser_snapshot
  • browser_act
  • browser_eval
  • browser_recover

Recovery is CCR-backed: browser_recover returns the byte-exact original AX payload for a snapshot handle.

Setup​

Caveman Browse is included in caveman setup --install. It requires Chrome to be installed.

caveman setup --install    # installs Browse alongside the proxy

MCP tools​

ToolDescription
browser_snapshotCapture the current page's accessibility tree. Supports an optional query parameter for token-efficient focus on large pages.
browser_actPerform an action (click, type, scroll, etc.) on an element by UID.
browser_evalExecute JavaScript in the page context.
browser_recoverReturn the byte-exact original AX payload for a snapshot handle via CCR.

browser_snapshot.query is the token-efficient path on large pages. It keeps best matching accessible nodes plus their ancestors while CCR retains the full raw tree. Compact output uses [uid] role "name" lines; only actionable or unknown custom roles spend UID tokens.

CLI usage​

Build the binary:

go build ./public/browse/cmd/caveman-browse

Run as MCP server:

caveman-browse

Direct CLI helper:

caveman-browse snapshot http://127.0.0.1:3000
caveman-browse snapshot http://127.0.0.1:3000 "save settings"
caveman-browse act <uid> click
caveman-browse recover <handle>
caveman-browse close

Direct commands share one detached, isolated Chrome until close; first use creates both profile and CCR directories.

Browser navigation allows http(s), about:blank, and bounded data:text/html; local files and privileged browser schemes fail closed.

Architecture​

Agent ──MCP──→ caveman-browse ──CDP──→ Chrome (AX tree)

Browse acts as an MCP server that translates MCP tool calls into Chrome DevTools Protocol (CDP) commands using the accessibility tree. The agent doesn't need to know about CDP — it just calls MCP tools.

Actions report settled:false after CDP dispatch because application state is not proven until another focused snapshot.