gamba-browser

Drive your real Chrome (with your real sessions) from scripts and AI agents, with a Playwright harness built for hostile SPAs.

• Runs over Chrome DevTools Protocol on a local profile: no cookies to export, no cloud browser, no per-action API cost.

• Ships an MCP server so Claude Code, Codex, Cursor or any MCP client can call it as native tools.

• Adds the helpers raw Playwright lacks: controlled inputs, split buttons, floating portals, blocked-button diagnostics.

Status: alpha. The driver is measured; the site recipes are examples, not guarantees. Expect rough edges.

Why

Raw Playwright is fine until a React/Vue app fights back: inputs revert, a hidden duplicate node receives the click, a portal menu never becomes "visible", a button is disabled for a reason that only exists inside React Fiber. gamba-browser packages the fixes for those cases and exposes them as one-call helpers.

Related MCP server: chrome-mcp

Install

git clone https://github.com/OscarJRM/gamba-browser.git
cd gamba-browser
npm install

Requires Node 18+. Chrome, Chromium, Brave or Edge must be installed.

Quick start

# 1. Verify the environment
node src/cli.js doctor

# 2. Log in once (the session stays in the profile directory)
node src/cli.js login https://x.com 3

# 3. Run Playwright against that live browser
node bin/gamba-exec -e 'await page.goto("https://example.com"); return await page.title()'

# 4. Target a specific tab
node bin/gamba-exec -e 'return page.url()' --target-url github.com

MCP server

node src/mcp.js

Client configuration:

{
  "mcpServers": {
    "gamba-browser": {
      "command": "node",
      "args": ["/absolute/path/to/gamba-browser/src/mcp.js"]
    }
  }
}

Tools: gamba_status, gamba_list_tabs, gamba_open, gamba_inspect_state, gamba_smart_fill, gamba_smart_click, gamba_smart_select, gamba_explain_disabled, gamba_screenshot.

The server keeps one CDP connection alive, so a multi-step agent loop does not pay process startup per call.

Harness helpers

All helpers are attached to the page (page.smartClick(...)) and to gamba-exec.

Configuration

Measured latency (not a marketing claim)

Same machine, same Playwright script, alternating runs, local fixture:

End-to-end X draft flow (trending -> profile -> compose -> text -> image -> save draft): 19.7 s vs 39.7 s in favor of this project, almost entirely because the relay charges a round-trip per keystroke. With insertText the gap shrinks to ~13%.

What this does not mean: that agents complete tasks better here. browse ships session handoff (2FA/CAPTCHA), recording, tab adoption and a mature MCP surface. This project is a faster local driver with a stronger SPA harness.

Methodology and raw fixture: bench/README.md.

Security

The DevTools port gives full control of a logged-in browser and has no authentication. Read SECURITY.md before using a profile with privileged accounts.

License

MIT