gepetto

gepettobrowser is a stealth Chrome for scrapers and coding agents. It launches a browser with a coherent, real-looking fingerprint, then records what each page does under the hood — its API calls, console errors and code — so an agent (or you) can drive it step by step and see exactly what every click caused. Use it from code, the gepetto CLI, or any MCP client.

• Stealth that holds up — one consistent identity across the page, Web Workers, WebGL and Client Hints; WebRTC leak protection; proxies with GeoIP-matched timezones; Cloudflare Turnstile.

• See inside the page — important requests only (documents, API/XHR/fetch, GraphQL, WebSockets) with JSON response shapes; trackers, beacons and assets filtered out. Every action reports the requests and errors it triggered.

• Share one browser — you, Claude Code, Cursor, Codex or a script can all attach to the same session; open it in a visible window to co-browse.

• Compact by design — text output an LLM reads in a few hundred tokens; full data stays on disk.

AI agents: point your agent at AGENTS.md — it's the complete usage guide (CLI, MCP tools, output formats, recipes). A ready-made Claude Code skill lives in skill/.

Install

npm install -g gepettobrowser     # the `gepetto` CLI + MCP server
npm install gepettobrowser        # as a library in your project

The MCP SDK and the optional AI plugin's SDK come along as optional dependencies. Point it at an installed Chrome for best results: export GEPETTO_EXECUTABLE_PATH=/usr/bin/google-chrome-stable.

Related MCP server: OpenCode in Chrome

Quick start

CLI — sessions start in the background and stay alive between commands:

gepetto open https://example.com     # → page digest; interactive elements get refs (e1, e2…)
gepetto act click e3                 # → what happened, the requests it fired, fresh digest
gepetto net                          # important requests on this page
gepetto close

MCP — register once, then ask your agent to use the gepetto_* tools:

claude mcp add -s user gepetto -- gepetto mcp

GUI apps don't inherit your shell's PATH, so use absolute paths (command -v npx):

// claude_desktop_config.json, ~/.cursor/mcp.json
{ "mcpServers": { "gepetto": {
    "command": "/absolute/path/to/npx",
    "args": ["-y", "gepettobrowser", "mcp"],
    "env": { "GEPETTO_EXECUTABLE_PATH": "/usr/bin/google-chrome-stable" } } } }

# ~/.codex/config.toml
[mcp_servers.gepetto]
command = "/absolute/path/to/npx"
args = ["-y", "gepettobrowser", "mcp"]

Library:

const { BrowserController } = require('gepettobrowser/control');

const ctl = new BrowserController({ headless: true, capture: true });
const page = await ctl.open('https://shop.example');           // digest with element refs
const res  = await ctl.act({ type: 'click', ref: 'e4' });       // outcome + activity + digest
console.log(res.activity.network.entries, ctl.console().entries);
await ctl.close();

See what the page does

One click on Add to cart shows the POST /api/cart it fired, the shape of the response, and the exception the page threw. Of the ten requests so far, only the four that matter are listed; the rest (images, the script, the stylesheet, an analytics beacon, a tracker) are counted under hidden.

gepetto net <id> gives a request's headers, body and a ready-to-run curl (with the session's cookies). gepetto code lists every script and stylesheet, the detected stack, and embedded state like __NEXT_DATA__; code search "<text or /regex/>" searches the live DOM plus every captured script and API response.

Everything is also stored on disk, deduplicated and greppable:

~/.gepetto/sessions/<id>/
  network.ndjson   one line per request      bodies/   API/HTML/JS/CSS bodies (content-addressed)
  console.ndjson   errors + exceptions       dom/      raw + condensed DOM snapshots

Share one browser

The process that starts a session publishes it on 127.0.0.1 behind a random token; anything else attaches by session id. Run gepetto live https://myapp.local --headed, click around, and your agent sees exactly what your clicks triggered — or let the agent drive the window while you watch.

Sandboxed shell agents such as Codex can use the CLI without MCP: start the session in a normal terminal (gepetto live <url> --detach --session codex), then attach with --session codex. The sandbox needs localhost access (sandbox_workspace_write.network_access = true in Codex).

Stealth

A fingerprint is one coherent, optionally seeded identity (fingerprint: true, a seed, or your own profile). It covers navigator.*, WebGL vendor/renderer (a real GPU, never SwiftShader), canvas and audio noise, screen metrics, plugins, permissions, UA + Client Hints + userAgentData — identically in the main thread, Web Workers and SharedWorkers — plus WebRTC leak blocking, GeoIP timezone alignment for proxies, and a Cloudflare Turnstile clicker.

Reference

gepetto fetch  <url>                       HTTP-first fetch (no browser) → text
gepetto browse <url> [--screenshot FILE]   one-shot stealth browser → visible text
gepetto view   [url] [--os windows|mac|iphone]   visible window for manual use
gepetto mcp                                run the MCP server on stdio

gepetto live [url] [--session ID] [--headed] [--proxy URL] [--detach] [--idle MIN]
gepetto open <url> [--find TEXT]           (auto-starts a background session)
gepetto digest [--find TEXT]
gepetto act click|hover <ref> | type <ref> "<text>" [--submit] | select <ref> "<option>"
            key <Key> | scroll [down|up] | navigate <url> | back | forward | reload | wait <ms> | tab <n>
gepetto net [<id>] [--since N] [--match RE] [--errors] [--all] [--kinds api,ws] [--scope session]
gepetto console [--level error|warn|log|all] [--since N]
gepetto code [summary | dom [--selector S] | get <s3|c1|#42|dom|url> | search "<text|/re/>"]
gepetto read [--html] [--eval "<js>"]  ·  gepetto shot [file]  ·  gepetto extract --fields '<json>'
gepetto sessions [--prune]  ·  gepetto close
common flags: --session ID · --json

Environment: GEPETTO_EXECUTABLE_PATH, GEPETTO_PROXY, GEPETTO_HEADED=1, GEPETTO_CAPTURE=0, GEPETTO_IDLE_MINUTES (default 60), GEPETTO_HOME (default ~/.gepetto), GEPETTO_KEEP_DAYS (default 7), GEPETTO_LOG_LEVEL. The server never reads a proxies.txt from its working directory.

const { init } = require('gepettobrowser');
const { browser, page } = await init({
  headless: false,            // default false (headed via xvfb on Linux unless disableXvfb)
  executablePath: undefined,  // or GEPETTO_EXECUTABLE_PATH
  screenSize: { width: 1280, height: 720 },
  fingerprint: false,         // true | seed | profile object
  turnstile: false,           // background Cloudflare Turnstile solver
  proxy: null,                // 'http://user:pass@host:port' · object · false (no proxy, ignore proxies.txt)
  proxies: null, proxyRotation: 'roundrobin', geoip: false,
  captcha: false,             // 2Captcha extension — see below
  captchaExtension: undefined, captchaApiKey: undefined,
  blockResources: false, blockAds: false,
  userDataDir: null, cookiesFile: null,
  inputDelay: 0,              // seconds of human mouse movement before click/type
  silent: false, logLevel: 'info', logger: null,
});
await page.gotoResilient('https://example.com'); // retries + challenge wait

The page also gets findAdaptive (self-healing selectors), saveCookies / loadCookies, realClick (ghost-cursor), and exportData. Types ship in the package.

2Captcha: the solver extension isn't bundled (it has no open-source license). Download it from rucaptcha/2captcha-solver releases, unzip, and pass captchaExtension: '/path/to/folder' with captchaApiKey (or TWOCAPTCHA_API_KEY).

const { aiScrape } = require('gepettobrowser/ai');   // needs @anthropic-ai/sdk + ANTHROPIC_API_KEY
const res = await aiScrape({ url, prompt: 'list the products as {name, price}', export: 'xlsx' });
// res.data · res.usage · res.cost · res.file

const { saveData } = require('gepettobrowser/export'); // zero-dependency CSV / XLSX / JSON / NDJSON
await saveData(rows, { format: 'xlsx', dir: './out', organize: 'domain/date' });

Development

npm run test:unit   # browser-free unit tests (what CI runs)
npm test            # headless smoke test

See CONTRIBUTING.md, SECURITY.md and CHANGELOG.md.

Responsible use

This is a browser automation tool. You're responsible for following the terms of the sites you visit and the laws that apply to you. Captured sessions contain cookies and response bodies — treat ~/.gepetto like a browser profile.

License

AGPL-3.0-only © 2025–2026 redhatzx. The launch layer started as a fork of puppeteer-real-browser (MIT) — see THIRD_PARTY_NOTICES.md.