browse

package module
v0.0.0-...-a60463e Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 30, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

README

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.

caveman-browse Playwright MCP Chrome DevTools MCP
Tool-definition cost (measured 2026-08-14) 297 tokens (4 tools) 3,422 tokens (24 tools) 4,507 tokens (29 tools)
Page representation compressed a11y tree aria-YAML (lossy) a11y snapshot
Focused query on a 200-row page ~98 tokens ~15.7k (full ARIA) full snapshot
Byte-exact recovery of the original tree yes (CCR) no no
Runtime 1 static Go binary + your Chrome Node + Chromium Node + Puppeteer + Chromium

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 the Apache License 2.0. Third-party notices: NOTICE. Part of the Caveman efficiency stack; the a11y compressor and CCR live in the Caveman engine.

Documentation

Index

Constants

View Source
const (
	ToolSnapshot = "browser_snapshot"
	ToolAct      = "browser_act"
	ToolEval     = "browser_eval"
	ToolRecover  = "browser_recover"
)

Variables

This section is empty.

Functions

func BrowserTools

func BrowserTools(s *Session) []mcp.Tool

func DefaultUserDataDir

func DefaultUserDataDir(home string) string

Types

type ActionRequest

type ActionRequest struct {
	Action string `json:"action"`
	UID    string `json:"uid"`
	Text   string `json:"text"`
	Option string `json:"option"`
}

type ActionResult

type ActionResult struct {
	OK      bool   `json:"ok"`
	UID     string `json:"uid,omitempty"`
	Settled bool   `json:"settled"`
	Note    string `json:"note,omitempty"`
}

type CDPDriver

type CDPDriver struct {
	// contains filtered or unexported fields
}

func NewCDPDriver

func NewCDPDriver(parent context.Context, opts CDPOptions) (*CDPDriver, error)

func (*CDPDriver) Act

func (d *CDPDriver) Act(ctx context.Context, req ActionRequest, target Target) (ActionResult, error)

func (*CDPDriver) Close

func (d *CDPDriver) Close() error

func (*CDPDriver) Eval

func (d *CDPDriver) Eval(ctx context.Context, expression string) (any, error)

func (*CDPDriver) Shutdown

func (d *CDPDriver) Shutdown(ctx context.Context) error

Shutdown closes the attached browser process. Ordinary Close only releases this driver context; direct CLI mode deliberately leaves its detached Chrome alive between snapshot and act commands until `browse close` calls Shutdown.

func (*CDPDriver) Snapshot

func (d *CDPDriver) Snapshot(ctx context.Context, url string, wait time.Duration) ([]byte, error)

func (*CDPDriver) TargetID

func (d *CDPDriver) TargetID() string

type CDPOptions

type CDPOptions struct {
	Endpoint    string
	UserDataDir string
	BrowserPath string
	Headless    bool
	TargetID    string
}

type Driver

type Driver interface {
	Snapshot(ctx context.Context, url string, wait time.Duration) ([]byte, error)
	Act(ctx context.Context, req ActionRequest, target Target) (ActionResult, error)
	Eval(ctx context.Context, expression string) (any, error)
	Close() error
}

type Session

type Session struct {
	// contains filtered or unexported fields
}

func NewSession

func NewSession(eng *engine.Engine, driver Driver, log *slog.Logger) *Session

func (*Session) Close

func (s *Session) Close() error

func (*Session) LoadTargets

func (s *Session) LoadTargets(targets map[string]Target)

func (*Session) TargetsSnapshot

func (s *Session) TargetsSnapshot() map[string]Target

type Target

type Target struct {
	BackendDOMNodeID int    `json:"backendDOMNodeId"`
	FrameID          string `json:"frameId,omitempty"`
	NodeID           string `json:"nodeId,omitempty"`
}

Directories

Path Synopsis
benchmarks
counttext command
Counts stdin with the Caveman offline o200k_base counter.
Counts stdin with the Caveman offline o200k_base counter.
toolcatalog/count command
Counts an MCP tool catalog's token cost with the same method the in-repo budget test uses: compact JSON of [{name, description, inputSchema}] counted by the Caveman offline o200k_base counter.
Counts an MCP tool catalog's token cost with the same method the in-repo budget test uses: compact JSON of [{name, description, inputSchema}] counted by the Caveman offline o200k_base counter.
cmd
caveman-browse command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL