{
"markdown": "# Crawlio Browser\n\n[](https://www.npmjs.com/package/crawlio-browser)\n[](LICENSE)\n[](https://github.com/Crawlio-app/crawlio-browser/actions/workflows/ci.yml)\n\n## [Documentation](https://docs.crawlio.app/browser-agent/overview) | [API Reference](https://docs.crawlio.app/browser-agent/tools) | [Chrome Extension](https://www.crawlio.app/browser-agent)\n\nMCP server that gives AI full control of a live Chrome browser via CDP. 150 tools with framework-aware intelligence, typed evidence infrastructure, tracking pixel analysis, technographic fingerprinting, SEO auditing, and confidence-tracked findings — captures what static crawlers can't see.\n\n## When to use Crawlio Browser\n\nUse Crawlio Browser when your AI needs to interact with a **real browser** — SPAs, authenticated pages, dynamic content, JS-rendered frameworks. Unlike headless browser tools, Crawlio Browser connects to **your actual Chrome** via a lightweight extension, giving the AI access to your logged-in sessions, cookies, and full browser state.\n\n**Crawlio Browser vs headless browser tools:** Headless tools launch a separate browser process. Crawlio Browser connects to your existing Chrome — no separate browser, no login flows, full access to your tabs and sessions.\n\n> [!WARNING]\n> This is the trade-off, stated plainly: connecting your own Chrome is the feature, and it means\n> an AI agent can act as you on every site you are logged into. It attaches Chrome's debugger to\n> the tab you connect, so it can read cookies, storage, and page content for that session.\n>\n> Review what you connect it to. Prefer a dedicated Chrome profile for agent work. Nothing is\n> captured until you connect a tab, and you can see the exact tool surface before configuring\n> anything by running `npx crawlio-browser tools`. Sites can opt out with\n> ``, which the extension honors.\n\n## Quick Start\n\n1. Install the [Chrome Extension](https://www.crawlio.app/browser-agent)\n2. Run the init wizard:\n ```bash\n npx crawlio-browser init\n ```\n\nThat's it. Auto-detects and configures 14 MCP clients: Claude Code, Cursor, VS Code, Codex, Gemini CLI, Claude Desktop, ChatGPT Desktop, Windsurf, Cline, Zed, Goose, OpenCode, MCPorter, and Cline CLI.\n\n### Init wizard options\n\n```bash\nnpx crawlio-browser init # Default: code mode, stdio transport\nnpx crawlio-browser init --full # Full mode (every tool exposed individually)\nnpx crawlio-browser init --portal # Portal mode (persistent HTTP server)\nnpx crawlio-browser init --cloudflare # Add Cloudflare MCP (89 tools, no wrangler)\nnpx crawlio-browser init --dry-run # Show what would happen\nnpx crawlio-browser init --yes # Skip prompts (CI / scripted installs)\nnpx crawlio-browser init -a claude # Target specific MCP client\n```\n\n### As an Agent Plugin\n\nThe package is also an [Agent Plugins](https://agent-plugins.org) v1 plugin, so a conformant client\ncan load it directly instead of running the wizard — `plugin.json` at the root, the eleven skills\nunder `skills/`, and the MCP server declared in `mcp.json`.\n\nThe product-facing `crawlio-*` workflows are folded into the eleven shipped skills. The similarly\nnamed definitions in `agents/` remain repo-local development fixtures: they import `src/evidence/*`\nand `loops/*`, neither of which is part of the npm runtime. They are excluded from `package.json`\ninstead of advertising a second, non-executable product surface.\n\nPoint the client at the installed package:\n\n```\nnode_modules/crawlio-browser # after `npm install crawlio-browser`\n```\n\n`mcp.json` resolves the server through `${PLUGIN_ROOT}/dist/mcp-server/index.js`, which is why the\nplugin has to be an **installed** package rather than an unpacked tarball — the server imports its\ndependencies at runtime, so a bare extract starts and then dies without answering.\n\n### Inspecting what it exposes\n\n```bash\nnpx crawlio-browser tools # What code mode exposes (the default)\nnpx crawlio-browser tools --full # Every tool, individually\nnpx crawlio-browser tools --json # Machine-readable, for diffing across versions\nnpx crawlio-browser doctor # Bridge, portal, native host, client configs\nnpx crawlio-browser --help # All commands and options\nnpx crawlio-browser --version # Version only\n```\n\nBoth are read-only and run without a browser, an extension, or a network connection — you can\nsee the whole surface before you configure any client. The numbers come from the same builders\nthe server registers, so they cannot disagree with what your client receives.\n\n### Transport Modes\n\n| Mode | Command / URL | Protocol | Best For |\n|------|--------------|----------|----------|\n| **stdio** | `npx crawlio-browser` | JSON-RPC over stdin/stdout | Claude Desktop, Cursor, Windsurf — client manages process lifecycle |\n| **Portal (HTTP)** | `POST http://127.0.0.1:3001/mcp` | MCP Streamable HTTP | Claude Code, ChatGPT Desktop — server survives session restarts |\n| **Portal (SSE)** | `GET /sse` + `POST /message` | Server-Sent Events | Legacy clients needing SSE transport |\n\nPortal mode is recommended for Claude Code — the server persists across context compaction and session restarts. On macOS, `--portal` installs a launchd agent for auto-start on login.\n\n### Manual setup (any client)\n\n\nPer-client manual config\n\n**Claude Desktop** — add to `claude_desktop_config.json`:\n```json\n{ \"mcpServers\": { \"crawlio-browser\": { \"command\": \"npx\", \"args\": [\"-y\", \"crawlio-browser\"] } } }\n```\n\n**Claude Code (Portal Mode)** — start `npx crawlio-browser --portal`, then add to `.mcp.json`:\n```json\n{ \"mcpServers\": { \"crawlio-browser\": { \"type\": \"http\", \"url\": \"http://127.0.0.1:3001/mcp\" } } }\n```\n\n**Claude Code (stdio):**\n```bash\nclaude mcp add crawlio-browser -- npx -y crawlio-browser\n```\n\n**Cursor** — add to `.cursor/mcp.json`:\n```json\n{ \"mcpServers\": { \"crawlio-browser\": { \"command\": \"npx\", \"args\": [\"-y\", \"crawlio-browser\"] } } }\n```\n\n**Windsurf** — add to Windsurf Settings > MCP:\n```json\n{ \"mcpServers\": { \"crawlio-browser\": { \"command\": \"npx\", \"args\": [\"-y\", \"crawlio-browser\"] } } }\n```\n\n**Cline (VS Code)** — add to `settings.json`:\n```json\n{ \"cline.mcpServers\": { \"crawlio-browser\": { \"command\": \"npx\", \"args\": [\"-y\", \"crawlio-browser\"] } } }\n```\n\n**ChatGPT Desktop** — Settings > Integrations > MCP:\nURL: `http://127.0.0.1:3001/mcp` | Type: Streamable HTTP\n\n\n\n## How It Works\n\n```\nAI Client (stdio/http) --> MCP Server (Node.js) --> Chrome Extension (MV3)\n crawlio-browser WebSocket -> CDP\n```\n\nThe MCP server communicates with the Chrome extension via WebSocket. The extension controls the browser through Chrome DevTools Protocol (CDP).\n\n## Capabilities\n\n### Framework-Aware Intelligence\n\nEvery `execute` call probes the browser for framework signatures and injects a shape-shifting `smart` object with framework-native accessors. React state, Vue reactivity, Next.js routing, Shopify cart data — 17 framework namespaces across 4 tiers, detected at runtime and rebuilt on every navigation. The AI doesn't query a generic DOM; it queries the framework's own data structures.\n\n### Evidence-Based Analysis\n\nMethod Mode adds higher-order methods and a typed evidence system on top of Code Mode. `smart.extractPage()` runs 7 parallel operations in a single call — page capture, performance metrics, security state, font detection, meta extraction, accessibility audit, and mobile-readiness check. Failed operations produce typed `CoverageGap` records instead of silent `null`s. Findings created with `smart.finding()` get their confidence automatically adjusted when supporting data is missing. The result: structured, auditable research output with gap tracking and confidence propagation.\n\n### Session Recording & Replay\n\nRecord browser interactions as structured data, then compile them into reusable SKILL.md automations. 12 interaction tools are automatically intercepted during recording — clicks, typing, navigation, scrolling — each capturing args, result, timing, and page URL. One `compileRecording()` call converts the session into a deterministic automation script.\n\n### Robot Training\n\nCapture human-guided browser demonstrations as replayable robot-training bundles. The default-mode\n`observe` lifecycle starts an event-driven recorder inside the extension; collection keeps running\nif the MCP process disconnects or restarts. On reconnection, `training_stop` exports the retained\nrun and materializes the complete 13-file RecordingBundle for replay and API synthesis. Full mode\nkeeps the existing `robot_training_*` names as compatibility aliases.\n\nPage monitoring is resident for the same reason: an extension-owned background tab and Chrome\nalarm collect bounded ARIA snapshots while no MCP server is present. Training and monitor history\nshare a 25 MiB local budget, with 20 completed training runs, 50 monitor jobs, 200 snapshots total,\nand 50 snapshots per monitor as count caps. Old completed data is evicted first; active work is\nnever silently evicted. Work starts only through explicit MCP lifecycle actions; the same actions\nreport status, stop collection, clear monitor snapshots, and—with an exact id plus explicit\nconfirmation—delete a stopped training/recording record from Chrome while preserving its\nmaterialized files. The extension popup remains a connection and browser-access status surface.\nStorage values are keys-only unless the caller explicitly opts in.\nMonitor snapshots intentionally retain compact ARIA page text locally; starting a monitor should\ntherefore be treated as consent to retain the visible content of that URL until it is cleared.\n\n### Auto-Settling & Actionability\n\nEvery mutative action (`click`, `type`, `navigate`, `select_option`) runs actionability checks before acting — polling visibility, dimensions, enabled state, and overlay detection. After the action, a progressive backoff settle delay (`[0, 20, 100, 100, 500]ms`) waits for DOM mutations to quiesce. The AI doesn't need manual `sleep()` calls between actions.\n\n### Several Tabs at Once\n\nAny command that acts on a page takes an optional `tabId` from `list_tabs`. Omit it and the command runs on the connected tab, exactly as before; supply one and it runs on that tab instead, with the whole command surface available on each. Commands overlap, so two tabs can be driven at the same time:\n\n```js\nconst [checkout, search] = await Promise.all([\n bridge.send({ type: \"browser_snapshot\", tabId: 42 }),\n bridge.send({ type: \"browser_snapshot\", tabId: 57 }),\n]);\n```\n\nTargeting a tab never changes which tab `connect_tab` points at, so an agent working several tabs cannot reassign the one a human is watching. Frame selection, coverage sessions, and framework detection are per tab. Network capture is the exception — it records one tab at a time and says which tab holds it rather than interleaving two.\n\n### Chrome Profiles\n\nAn extension instance is confined to its own Chrome profile and cannot see any other, so with Crawlio enabled in more than one, commands land in whichever profile connected first. `list_profiles` shows the profiles that have connected and which is being driven; `switch_profile` moves the connection to another. One profile is driven at a time — the released extension reconnects in the background, so switching back is immediate.\n\nProfiles identify themselves with a UUID minted into their own extension storage. It distinguishes a profile without describing it: no account, no email, no path, and no additional permission.\n\nSelecting a profile keeps cooperating extensions out of each other's way — it is not a security boundary, since the id is asserted by the extension rather than proved. The bridge's existing protections are unchanged: one extension at a time, and each must prove the server holds the real bridge token before anything executes.\n\n## Architecture\n\nA layered execution architecture where each layer absorbs a category of complexity that would otherwise fall on the model. The model sees four primary tools and a clean SDK. Everything beneath that surface is the runtime absorbing reality.\n\nThe layer worth understanding is the one that assembles itself. Detection runs against the live page on first use, and the `smart` object is built to match what that page turned out to be — `smart.react.*` exists only where React does. Nothing about the target is known at startup, so the surface is composed per tab rather than declared up front.\n\n```\n ┌───────────────────────────────────┐\n │ AI Model (LLM) │\n │ Writes code, reads errors, loops │\n └───────────────┬───────────────────┘\n │ search, execute, observe, connect_tab (+ 3 job tools)\n ▼\n┌─────────────────────────────────────────────────────────────────┐\n│ Crawlio Browser runtime │\n│ │\n│ ┌────────────────────────────────────────────────────────────┐ │\n│ │ METHOD MODE │ │\n│ │ Behavioral protocol + higher-order methods │ │\n│ │ scrollCapture · waitForIdle · extractPage · comparePages │ │\n│ │ detectTables · extractTable · waitForNetworkIdle · │ │\n│ │ extractData │ │\n│ │ │ │\n│ │ ↳ Absorbs: behavioral variance, ad-hoc composition, │ │\n│ │ inconsistent output shapes, data extraction patterns │ │\n│ ├────────────────────────────────────────────────────────────┤ │\n│ │ POLYMORPHIC CONTEXT │ │\n│ │ 17 framework namespaces, injected Just-In-Time │ │\n│ │ react · vue · angular · nextjs · shopify · ... │ │\n│ │ │ │\n│ │ ↳ Absorbs: framework opacity, minified code, │ │\n│ │ devtools hook complexity │ │\n│ ├────────────────────────────────────────────────────────────┤ │\n│ │ ACTIONABILITY ENGINE │ │\n│ │ 7 core smart methods with built-in resilience │ │\n│ │ click · type · navigate · waitFor · evaluate · │ │\n│ │ snapshot · rebuild │ │\n│ │ │ │\n│ │ ↳ Absorbs: DOM timing, hydration delays, CSS animations, │ │\n│ │ disabled states, overlapping elements │ │\n│ ├────────────────────────────────────────────────────────────┤ │\n│ │ TETHERED IPC BRIDGE │ │\n│ │ WebSocket ↔ Chrome extension, message queue, │ │\n│ │ heartbeat, auto-reconnect, stale detection │ │\n│ │ │ │\n│ │ ↳ Absorbs: connection drops, tab refreshes, │ │\n│ │ port conflicts, extension lifecycle │ │\n│ ├────────────────────────────────────────────────────────────┤ │\n│ │ COMMAND CHANNEL │ │\n│ │ bridge.send → CDP browser control via the extension │ │\n│ │ crawlio.* → Crawlio HTTP endpoints │ │\n│ │ Live searchable catalog: browser + Crawlio HTTP │ │\n│ └────────────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n │\n ▼\n ┌───────────────────────────────────┐\n │ Live Chrome Browser │\n │ Persistent session, real DOM, │\n │ framework runtime, user state │\n └───────────────────────────────────┘\n```\n\n### What Each Layer Absorbs\n\n| Layer | Without It | With It |\n|-------|-----------|---------|\n| **Tethered IPC Bridge** | Script crashes on tab refresh, pending commands lost on reconnect, port conflicts on startup | Resilient WebSocket with message queue (100-msg capacity), heartbeat stale detection (15s intervals), auto-reconnect with drain |\n| **Actionability Engine** | `click('#btn')` fires before the button renders, during CSS transitions, or while an overlay covers it | Progressive polling (exists → has dimensions → visible → not disabled → not obscured) with `[0, 20, 100, 100, 500]ms` backoff |\n| **Polymorphic Context** | Model sees minified `
` elements; reading React state requires knowing exact hook paths, renderer maps, and fiber root API | Runtime probes live JS environment, recognizes 64 frameworks and attaches up to 17 matching namespaces (`smart.react.getVersion()`, `smart.nextjs.getData()`) |\n| **Method Mode** | Model composes primitives ad-hoc — inconsistent scroll loops, missed edge cases, varying return shapes | 18 tested methods encode correct patterns; behavioral protocol constrains workflow |\n\n### Execution Lifecycle\n\n1. **Discovery** — Model calls `search(\"page capture performance\")` and gets documentation for relevant commands\n2. **Framework Detection** — Runtime probes the live DOM, detects active frameworks, constructs polymorphic `smart` object with appropriate namespaces\n3. **Scope Assembly** — Model's code is compiled into an async function with injected parameters: `bridge` (the browser command channel), `crawlio` (HTTP client), `sleep`, `TIMEOUTS`, `smart` (7 core + 18 higher-order methods + up to 17 framework namespaces), `compileRecording`\n4. **Execution** — Method Mode methods compose the lower layers: `extractPage()` fires 7 parallel `bridge.send()` calls; `click()` runs the actionability engine; `react.getVersion()` evaluates framework-specific expressions\n5. **Error Recovery (Agentic REPL)** — On failure, the browser stays in the exact state that produced the error. The model reads the structured error, adjusts, and calls `execute` again. Framework cache persists — no re-detection unless URL changed\n\n### Design Principles\n\n1. **Absorb complexity downward** — Every category of difficulty (connection management, DOM timing, framework detection, multi-step composition) is handled by the layer best equipped for it. The model only encounters the clean interface at the top.\n2. **Shape the SDK to the target** — The polymorphic context system detects what the page is and reshapes available methods to match. The model writes against a stable interface; the runtime adapts underneath.\n3. **Preserve state across cycles** — The tethered architecture means the model can fail, learn, and retry against the same live environment — transforming error handling from \"restart from scratch\" into \"adjust and continue.\"\n\n### How It Compares\n\nCode Mode is Cloudflare's idea and a good one: present tools as a typed API and let the model\nwrite code against it, because models have seen far more code than tool calls. Crawlio Browser\napplies that pattern to a target it was not built for — a live browser holding your session.\nThis is an MCP server, not an alternative to MCP.\n\n| Dimension | Standard MCP | Cloudflare Code Mode | Crawlio Browser |\n|-----------|-------------|---------------------|-----------------|\n| **Tools in context** | 50-100+ schemas | 2 (`search`, `execute`) | 7 (4 primary + 3 async job tools) |\n| **Execution environment** | N/A (tool calls) | V8 isolate (stateless) | Local async sandbox, tethered to a live browser |\n| **DOM access** | Via individual tool calls | None | Live, persistent, framework-aware |\n| **Framework awareness** | None | None | up to 17 namespaces, attached per page |\n| **Action resilience** | Model must handle timing | N/A (no DOM) | Built-in actionability polling + settle delays |\n| **Error recovery** | Re-call individual tool | Re-create isolate | Re-run against the state that produced the error |\n| **Multi-step patterns** | Model improvises | Model writes loops | 18 tested higher-order methods + behavioral protocol |\n\nThe row that matters is error recovery. An isolate is disposable by design — that is what makes\nit safe to run untrusted code, and it means a failure discards the state that caused it. Here\nexecution is tethered to a real tab, so when code fails the browser is still sitting in exactly\nthe situation that broke it: same scroll position, same modal, same half-filled form. The model\nreads the error and runs again against that. Neither approach is better in general; they are\nanswers to different problems, and the sandboxing guarantees Cloudflare gets from V8 isolates\nare genuinely stronger than what a local async sandbox provides.\n\n[Read the full architecture guide →](https://docs.crawlio.app/browser-agent/overview)\n\n## Two Modes\n\n### Code Mode (4 primary tools) — default\n\nCollapses 150 tools into four high-level tools, plus `get_job_result`,\n`list_jobs`, and `cancel_job` for async execution — so `tools/list` reports\n7.\n\nThat makes the `tools/list` payload **85% smaller**, measured by\nserializing the result each mode actually returns rather than estimated from a tool count. Code\nmode is not free: `execute` and `search` carry long descriptions, so the measured reduction is\nsmaller than a naive tools-only ratio suggests. Check it yourself — `npx crawlio-browser\ntools --json` prints both surfaces without connecting to anything.\n\n| Tool | Description |\n|------|-------------|\n| `search` | Discover available commands by keyword |\n| `execute` | Run async JS with `bridge`, `crawlio`, `smart`, `sleep`, and `compileRecording` in scope |\n| `observe` | Start/query/stop extension-resident training, recording, and page monitors |\n| `connect_tab` | Connect to a browser tab |\n\n```javascript\n// Navigate and screenshot\nawait bridge.send({ type: 'browser_navigate', url: 'https://example.com' }, 30000);\nawait sleep(2000);\nconst screenshot = await bridge.send({ type: 'take_screenshot' }, 10000);\nreturn screenshot;\n```\n\n### Full Mode (150 tools)\n\nEvery tool exposed directly to the LLM. Enable with `--full`:\n\n```bash\nnpx crawlio-browser init --full\n```\n\n## Smart Object\n\nIn Code Mode, the `smart` object provides framework-aware helpers with auto-waiting and actionability checks.\n\n### Core Methods\n\n| Method | Description |\n|--------|-------------|\n| `smart.evaluate(expression)` | Execute JS in the page via CDP |\n| `smart.click(selector, opts?)` | Auto-waiting click with 500ms settle |\n| `smart.type(selector, text, opts?)` | Auto-waiting type with 300ms settle |\n| `smart.navigate(url, opts?)` | Navigate with 1000ms settle |\n| `smart.waitFor(selector, timeout?)` | Poll until element is actionable |\n| `smart.snapshot()` | Accessibility tree snapshot |\n| `smart.rebuild()` | Re-detect frameworks and reattach namespaces for the current page |\n\n### Higher-Order Methods\n\n| Method | Description |\n|--------|-------------|\n| `smart.scrollCapture(opts?)` | Scroll to bottom, capturing screenshots at each position. Handles stuck-scroll detection, bottom detection, section capping, and scroll reset. |\n| `smart.waitForIdle(timeout?)` | MutationObserver-based idle detection — waits for 500ms quiet window. Timeout hard-capped at 15s. Replaces blind `sleep()` calls. |\n| `smart.extractPage(opts?)` | 7 parallel operations in one call — page capture, performance, security, fonts, meta, accessibility, mobile-readiness. Returns typed `PageEvidence` with `CoverageGap[]` for anything that failed. |\n| `smart.comparePages(urlA, urlB)` | Navigates to both URLs, runs `extractPage()` on each, returns a `ComparisonScaffold` with 11 dimensions, shared/missing fields, and comparable metrics. |\n\n### Typed Evidence\n\nMethods for structured analysis findings with confidence propagation:\n\n| Method | Description |\n|--------|-------------|\n| `smart.finding(data)` | Create a validated `Finding` with claim, evidence, sourceUrl, confidence, and method. Rejects malformed input with specific errors. |\n| `smart.findings()` | Get all session-accumulated findings (returns a copy) |\n| `smart.clearFindings()` | Reset session findings and coverage gaps |\n\nWhen a finding's `dimension` matches an active coverage gap, confidence is automatically capped:\n\n| Input Confidence | Active Gap | Output |\n|-----------------|------------|--------|\n| `high` | `reducesConfidence: true` | `medium` + `confidenceCapped: true` |\n| `medium` | `reducesConfidence: true` | `low` + `confidenceCapped: true` |\n| `low` | any | `low` (floor) |\n| any | no matching gap | unchanged |\n\n### Framework Namespaces\n\nWhen a framework is detected, the smart object exposes framework-specific helpers:\n\n\nReact — smart.react\n\n| Method | Returns |\n|--------|---------|\n| `getVersion()` | Version string and bundle type |\n| `getRootCount()` | Number of React root components |\n| `hasProfiler()` | Whether profiler is available |\n| `isHookInstalled()` | Whether DevTools hook is installed |\n\n\n\n\nVue.js — smart.vue\n\n| Method | Returns |\n|--------|---------|\n| `getVersion()` | Vue version string |\n| `getAppCount()` | Number of Vue app instances |\n| `getConfig()` | App config object |\n| `isDevMode()` | Whether DevTools is enabled |\n\n\n\n\nAngular — smart.angular\n\n| Method | Returns |\n|--------|---------|\n| `getVersion()` | ng-version attribute value |\n| `isDebugMode()` | Whether debug APIs available |\n| `isIvy()` | Whether Ivy compiler is active |\n| `getRootCount()` | Number of Angular root elements |\n| `getState()` | Full state object |\n\n\n\n\nSvelte — smart.svelte\n\n| Method | Returns |\n|--------|---------|\n| `getVersion()` | Svelte version string |\n| `getMeta()` | Svelte metadata object |\n| `isDetected()` | Whether Svelte is detected |\n\n\n\n\nRedux — smart.redux\n\n| Method | Returns |\n|--------|---------|\n| `isInstalled()` | Whether Redux DevTools is installed |\n| `getStoreState()` | Full store state |\n\n\n\n\nAlpine.js — smart.alpine\n\n| Method | Returns |\n|--------|---------|\n| `getVersion()` | Alpine version string |\n| `getStoreKeys()` | Store object keys |\n| `getComponentCount()` | Count of `[x-data]` components |\n\n\n\n\nNext.js — smart.nextjs\n\n| Method | Returns |\n|--------|---------|\n| `getData()` | `__NEXT_DATA__` object |\n| `getRouter()` | Router state (pathname, query, asPath) |\n| `getSSRMode()` | SSR mode (hybrid, app-router, static) |\n| `getRouteManifest()` | Current page data |\n\n\n\n\nNuxt — smart.nuxt\n\n| Method | Returns |\n|--------|---------|\n| `getData()` | `__NUXT__` object |\n| `getConfig()` | App config |\n| `isSSR()` | Whether server-rendered |\n\n\n\n\nRemix — smart.remix\n\n| Method | Returns |\n|--------|---------|\n| `getContext()` | `__remixContext` object |\n| `getRouteData()` | Loader data from state |\n\n\n\n\nShopify — smart.shopify\n\n| Method | Returns |\n|--------|---------|\n| `getShop()` | Shop metadata (theme, locale, currency) |\n| `getCart()` | Shopping cart object |\n\n\n\n\nWordPress — smart.wordpress\n\n| Method | Returns |\n|--------|---------|\n| `isWP()` | Whether WordPress is present |\n| `getRestUrl()` | REST API endpoint |\n| `getPlugins()` | List of active plugins |\n\n\n\n\nMore frameworks — Gatsby, WooCommerce, Laravel, Django, Drupal, jQuery\n\n| Namespace | Methods |\n|-----------|---------|\n| `smart.gatsby` | `getData()`, `getPageData()` |\n| `smart.woocommerce` | `getParams()` |\n| `smart.laravel` | `getCSRF()` |\n| `smart.django` | `getCSRF()` |\n| `smart.drupal` | `getSettings()` |\n| `smart.jquery` | `getVersion()` |\n\n\n\n## Method Mode\n\nCode Mode asks the model to write code. Method Mode gives that code a tested vocabulary:\n18 higher-order methods that encode the multi-step patterns a model\nwould otherwise improvise.\n\n```javascript\nawait smart.extractTable(selector) // not a hand-rolled scrape loop\nawait smart.scrollCapture() // not a guessed scroll cadence\n```\n\nIt is a domain layer over Code Mode, not a replacement: the tool surface does not change, the\nmodel still sees the same four primary tools, and the same 182-command\ncatalog sits underneath. What changes is what happens *inside* `execute`.\n\nThe surface is assembled per page. Detection recognizes 64\nframeworks and attaches up to 17 matching namespaces, so `smart.react.*`\nexists only where React does — the model never has to ask what the page is built with, or guess\nat hook paths and fiber internals to find out.\n\nAnd because execution is tethered to a live tab rather than a disposable isolate, a failure\nleaves the browser in the exact state that produced it. The model reads the structured error and\nruns again against that state, rather than rebuilding the situation from scratch.\n\n### The Maturity Ladder\n\n| Layer | Optimizes For | Behavioral Variance | Evidence Quality |\n|-------|---------------|---------------------|-----------------|\n| **Raw MCP** (150 tools) | Completeness | High — flat tool list, no composition guidance | None — unstructured text |\n| **Code Mode** (7 tools) | Token efficiency | Medium — right primitives, ad-hoc composition | None — model-defined shapes |\n| **Method Mode** (+ 18 methods + protocol) | Consistency | Low — proper methods, protocol constraints | Convention — `{ finding, evidence, url }` |\n| **+ typed evidence** (gaps + confidence) | Correctness | Minimal — typed schemas, tool-enforced findings | Structural — typed records, gap tracking, confidence propagation |\n\n### Architecture\n\n```\n┌────────────────────────────────────────────────────────────┐\n│ execute sandbox │\n│ │\n│ ┌──────────────────────────────────────────────────────┐ │\n│ │ Behavioral Protocol (web-research skill) │ │\n│ │ Acquire → Normalize → Analyze │ │\n│ ├──────────────────────────────────────────────────────┤ │\n│ │ Evidence Infrastructure │ │\n│ │ finding() · findings() · clearFindings() │ │\n│ │ Typed records · Coverage gaps · Confidence prop. │ │\n│ ├──────────────────────────────────────────────────────┤ │\n│ │ Higher-Order Methods [18] │ │\n│ │ scrollCapture · waitForIdle · extractPage · │ │\n│ │ comparePages · detectTables · extractTable · │ │\n│ │ waitForNetworkIdle · extractData · detectSections · │ │\n│ │ detectTechnologies · parseTrackingPixels · ... │ │\n│ ├──────────────────────────────────────────────────────┤ │\n│ │ Smart Core [7 methods] │ │\n│ │ evaluate · click · type · navigate · waitFor · │ │\n│ │ snapshot · rebuild │ │\n│ ├──────────────────────────────────────────────────────┤ │\n│ │ Framework Namespaces [up to 17, attached per page] │ │\n│ │ react · vue · angular · nextjs · shopify · ... │ │\n│ ├──────────────────────────────────────────────────────┤ │\n│ │ bridge.send() — the browser command channel │ │\n│ └──────────────────────────────────────────────────────┘ │\n└────────────────────────────────────────────────────────────┘\n```\n\nEach layer up encodes more domain knowledge. `bridge.send({ type: \"capture_page\" })` captures a page. `smart.extractPage()` captures a page AND runs performance metrics, security state, font detection, accessibility analysis, and mobile-readiness checks in parallel — seven operations, one call, graceful failure on supplementary data, typed gaps for anything that fails.\n\n### Evidence Infrastructure\n\n**Coverage Gaps** — When supplementary operations in `extractPage()` fail, they don't silently return `null`. A typed gap is recorded with the dimension, reason, impact, and whether it reduces confidence on related findings:\n\n```javascript\n// Example gap from a failed performance metrics call\n{ dimension: \"performance\", reason: \"CDP domain disabled\", impact: \"method-failed\", reducesConfidence: true }\n```\n\n**Tool-Enforced Findings** — `smart.finding()` validates every field at the tool level. The model cannot produce a finding without meeting the schema — it either returns a valid `Finding` or gets a clear error. Findings accumulate across `execute` calls within a session via `smart.findings()`.\n\n**Session Aggregation** — Findings and coverage gaps persist across `execute` calls. A model can make findings across multiple calls, then retrieve the full set with `smart.findings()`. Reset with `smart.clearFindings()`.\n\n### End-to-End Example: Competitive Audit\n\n```javascript\n// 1. Extract and compare both sites (scaffold + gaps included)\nconst comparison = await smart.comparePages(\n 'https://acme.com',\n 'https://rival.com'\n);\n\n// 2. Make findings — confidence auto-adjusts based on data availability\nsmart.finding({\n claim: 'Rival loads 2.3x faster on Largest Contentful Paint',\n evidence: [\n `Acme LCP: ${comparison.siteA.performance?.webVitals?.lcp}ms`,\n `Rival LCP: ${comparison.siteB.performance?.webVitals?.lcp}ms`,\n ],\n sourceUrl: 'https://acme.com',\n confidence: 'high',\n method: 'comparePages + extractPage performance metrics',\n dimension: 'performance', // if perf data failed, confidence caps to \"medium\"\n});\n\nsmart.finding({\n claim: 'Acme has 12 images without alt text; Rival has 0',\n evidence: [\n `Acme imagesWithoutAlt: ${comparison.siteA.accessibility?.imagesWithoutAlt}`,\n `Rival imagesWithoutAlt: ${comparison.siteB.accessibility?.imagesWithoutAlt}`,\n ],\n sourceUrl: 'https://acme.com',\n confidence: 'high',\n method: 'comparePages + extractPage accessibility summary',\n dimension: 'accessibility',\n});\n\n// 3. Capture visual evidence\nawait smart.navigate('https://acme.com');\nawait smart.waitForIdle();\nconst acmeVisuals = await smart.scrollCapture({ maxSections: 5 });\n\n// 4. Return accumulated session findings + visual evidence\nreturn {\n findings: smart.findings(),\n scaffold: comparison.scaffold,\n gaps: { acme: comparison.siteA.gaps, rival: comparison.siteB.gaps },\n visualEvidence: { acme: acmeVisuals.sectionCount + ' sections captured' },\n};\n```\n\n## Examples\n\n#### Navigate, extract, and analyze\n\n```javascript\n// Connect to active tab, extract structured page evidence\nconst page = await smart.extractPage();\nconst finding = smart.finding({\n claim: `Site uses ${page.capture.framework?.name || 'no detected framework'}`,\n evidence: [`Framework: ${JSON.stringify(page.capture.framework)}`],\n sourceUrl: page.meta?.canonical || 'active tab',\n confidence: 'high',\n method: 'extractPage framework detection',\n});\nreturn { page: page.meta, finding };\n```\n\n#### Mobile emulation + screenshot\n\n```javascript\n// Emulate iPhone and capture\nawait bridge.send({ type: 'emulate_device', device: 'iPhone 14' }, 10000);\nawait smart.navigate('https://example.com');\nawait smart.waitForIdle();\nconst screenshot = await bridge.send({ type: 'take_screenshot' }, 10000);\nreturn screenshot;\n```\n\n#### Record and compile automation\n\n```javascript\n// Record a browser session, then compile to reusable skill\nawait bridge.send({ type: 'start_recording' }, 10000);\nawait smart.navigate('https://example.com');\nawait smart.click('button.submit');\nawait smart.type('#email', 'test@example.com');\nconst session = await bridge.send({ type: 'stop_recording' }, 10000);\nreturn compileRecording(session.session, 'signup-flow');\n```\n\n#### Intercept and mock network\n\n```javascript\n// Block analytics, mock API response\nawait bridge.send({\n type: 'browser_intercept',\n pattern: '*analytics*',\n action: 'block'\n}, 10000);\nawait bridge.send({\n type: 'browser_intercept',\n pattern: '*/api/user',\n action: 'mock',\n body: JSON.stringify({ name: 'Test User' }),\n statusCode: 200\n}, 10000);\nawait smart.navigate('https://example.com');\nreturn await smart.snapshot();\n```\n\n## Session Recording\n\nRecord browser sessions as structured data, then compile them into reusable automation skills. 12 interaction tools are automatically intercepted during recording (click, type, navigate, scroll, etc.), capturing args, result, timing, and page URL.\n\n```javascript\n// In code mode: record, interact, compile\nawait bridge.send({ type: 'start_recording' }, 10000);\n// ... interact with the page ...\nconst session = await bridge.send({ type: 'stop_recording' }, 10000);\nconst skill = compileRecording(session.session, 'my-automation');\nreturn skill;\n```\n\nIn full mode, recording is available as 4 individual tools: `start_recording`, `stop_recording`, `get_recording_status`, and `compile_recording`.\n\n## Auto-Settling\n\nMutative tools (`browser_click`, `browser_type`, `browser_navigate`, `browser_select_option`) use actionability checks:\n\n1. **Pre-flight**: Polls element visibility, stability, and enabled state before acting\n2. **Action**: Dispatches the CDP command\n3. **Post-settle**: Waits for DOM mutations to quiesce with progressive backoff `[0, 20, 100, 100, 500]ms`\n\nThis means the AI doesn't need to manually add `sleep()` or `waitFor()` calls between actions — the tools handle SPA rendering delays automatically.\n\n## Framework Detection\n\nDetects **64 technologies** across 4 tiers using globals, DOM markers, meta tags, HTTP headers, and script URLs:\n\n| Tier | Frameworks | Signal Strength |\n|------|-----------|----------------|\n| **Meta-frameworks** | Next.js, Nuxt, SvelteKit, Remix, Gatsby | Unique globals + parent detection |\n| **Core** | React, Vue.js, Angular, Svelte, Astro, Qwik, SolidJS, Lit, Preact | Globals + DOM markers |\n| **CMS & Platforms** | WordPress, Shopify, Webflow, Squarespace, Wix, Drupal, Magento, Ghost, Bubble | Meta tags + globals |\n| **Libraries & Tools** | jQuery, Bootstrap, Tailwind CSS, Alpine.js, HTMX, Turbo, Stencil, Redux, Ember.js, Backbone.js | DOM + globals |\n\nMulti-framework detection returns a **primary** framework (meta-framework takes priority) plus a `subFrameworks` array for the full stack.\n\n## Tools Reference\n\nThe table below is a hand-written guide to the commonly used tools, not the complete set. For\nthe full, current surface — all 150 of them, read from the server itself —\nrun `npx crawlio-browser tools --full`.\n\n\nTool reference — Connection, Capture, Navigation, Network, Storage, Emulation, Tracking, SEO, and more\n\n### Connection & Status\n\n| Tool | Description |\n|------|-------------|\n| `connect_tab` | Connect to a browser tab by URL, tab ID, or active tab |\n| `disconnect_tab` | Disconnect from the current tab |\n| `list_tabs` | List all open tabs with IDs and URLs |\n| `get_connection_status` | Check CDP connection state |\n| `reconnect_tab` | Force reconnect to fix stale connections |\n| `get_capabilities` | Report live browser-bridge availability by tab, CDP domain, and permission state |\n\n### Page Capture\n\n| Tool | Description |\n|------|-------------|\n| `capture_page` | Full capture: framework + network + console + DOM |\n| `detect_framework` | Detect JS framework and version |\n| `start_network_capture` | Start recording network requests |\n| `stop_network_capture` | Stop recording and return captured requests |\n| `get_console_logs` | Get console logs (errors, warnings, info) |\n| `get_cookies` | Get cookies (sensitive values redacted) |\n| `get_dom_snapshot` | Simplified DOM tree with shadow DOM and iframe support |\n| `take_screenshot` | Viewport/full-page/element image (JPEG default, PNG on request) |\n| `get_response_body` | Get response body for a captured network request |\n\n### Navigation & Interaction\n\n| Tool | Description |\n|------|-------------|\n| `browser_navigate` | Navigate to a URL (auto-settle) |\n| `browser_click` | Click element by CSS selector (auto-settle, left/right/middle, modifiers) |\n| `browser_double_click` | Double-click element |\n| `browser_type` | Type text into element (auto-settle) |\n| `browser_press_key` | Press keyboard key (Enter, Tab, Escape, shortcuts) |\n| `browser_hover` | Hover over element |\n| `browser_select_option` | Select `\n\n## Requirements\n\n- **Node.js** >= 18\n- **Chrome** (or Chromium) with the [Crawlio for Chrome extension](https://www.crawlio.app/browser-agent) installed\n- **Crawlio.app** (optional) — for site crawling and enrichment\n\n### Permission floor\n\nThe production extension has no standing host access. Its required permissions are `debugger`\n(the CDP control plane), `storage` (bridge/session settings and durable resident metadata), and\n`alarms` (reconnect, idle-release, and resident monitor wakeups). The dedicated onboarding page\nasks once for every optional capability declared by the active build. In production that is `tabs`,\n`nativeMessaging`, and `http://127.0.0.1/*`, covering tab discovery/adoption, authenticated local\ntoken provisioning, and loopback bridge discovery.\n\nOnboarding is the only surface that can open Chrome's permission prompt. The extension popup and\nMCP tools only report missing access and route the user back to onboarding. `connect_tab({url})`,\nagent-owned tabs, robot training, and resident monitoring can still create and control their own\ntabs if the `tabs` metadata grant is denied. Crawlio does not request ``, `activeTab`,\n`tabGroups`, or `unlimitedStorage`.\n\n## Build from Source\n\n```bash\ngit clone https://github.com/Crawlio-app/crawlio-browser.git\ncd crawlio-browser\nnpm install\nnpm run build # selectors → semantic-grounding → MCP server → extension\n```\n\nBuild output lands in `dist/mcp-server/` (ESM bundle) and `dist/extension/` (the\nunpacked MV3 extension).\n\nTo develop against the extension, build the dev variant and load it unpacked:\n\n```bash\nnpm run build:dev # → dist/extension-dev, with __DEV__ logging enabled\n```\n\nThen open `chrome://extensions`, enable Developer mode, choose **Load unpacked**,\nand select `dist/extension-dev`. Reload the extension there after each rebuild.\n\n```bash\nnpm test # vitest\nnpm run typecheck # server + extension TypeScript projects\n```\n\n## Resources\n\n- [Documentation](https://docs.crawlio.app/browser-agent/overview)\n- [API Reference](https://docs.crawlio.app/browser-agent/tools)\n- [Product Page](https://www.crawlio.app/browser-agent)\n- [Chrome Extension](https://www.crawlio.app/browser-agent)\n- [npm Package](https://www.npmjs.com/package/crawlio-browser)\n- [Source](https://github.com/Crawlio-app/crawlio-browser)\n- [Changelog](CHANGELOG.md) | [Releases](https://github.com/Crawlio-app/crawlio-browser/releases)\n\n## Contributing\n\nContributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the build\nand development loop, and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community\nexpectations. Please report security vulnerabilities privately via\n[SECURITY.md](SECURITY.md) rather than in a public issue.\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE).\n\nThe selector kernel in [`packages/selectors`](packages/selectors) is MIT-licensed:\nit contains code ported from Selector Forge (MIT) and Chromium DevTools\n(BSD-3-Clause). See [`packages/selectors/LICENSE`](packages/selectors/LICENSE) and\n[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for full attributions.\n",
"bytes": 50395,
"sha": "66e0d3d72f68b8bf91980772c26dfae1fb7af9cd011d3a3c2f94a7464802c532",
"repo_slug": "crawlio-app/crawlio-browser",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_app_crawlio_crawlio_browser_f293f722/readme"
}