Skip to main content
Glama
Luculent Browser Driver

Luculent Browser Driver

Browser Driver for AI Agents

A fast, persistent browser driver for AI agents, with Chrome security controls built in.

Built by Luculent: SOPs for AI agents. Join the beta at luculent.dev/beta


Benchmark results

Every number below comes from a run log committed to this repo. Full tables and logs: harness/RESULTS.md.

  • Driver speed: a 7-action sign-up form takes 131 ms in one call with Luculent (headless) vs 1,748 ms with Playwright MCP 0.0.85, on the same pages and machine (median of 7, no model involved).

  • Fewer calls, less to read: the form is 1 tool call instead of 7, and the agent reads 0.8 KB instead of 4.0 KB.

  • Real models: DeepSeek v4.1 Flash and Codex CLI each passed 10/10 harness tasks (form, search, multitab, dynamic, upload, iframe, hover, drag, popup, guard). DeepSeek's 10 runs cost $0.0177 in total.

  • Broad suite: 35/37 local fixture cases and 51/55 live public sites pass headless (3 of the 4 live misses were sites that block headless browsers).



Claude Desktop, Cursor, Codex, Gemini CLI or your own script talk to one local relay with an API key. The relay drives your real Chrome tabs through a small MV3 extension, or a clean headless Chrome for background jobs.

agent --MCP / HTTP / WebSocket + API key--> relay (127.0.0.1:47800) --WebSocket--> extension --chrome.debugger--> your tabs
                                                     \------------------ CDP -----------------> headless Chrome
  • Fast. browser_run batches many steps (navigate, type, click, wait, extract) into one call, and snapshots return one line per interactive element, or only what changed. No screenshots unless you ask.

  • Predictive lookahead. Anticipates the next 2-3 actions with site priors and resolves intents against the live DOM in code, clearing modal blockers with zero LLM turns.

  • No reconnects. One persistent connection that survives Chrome suspending the extension's service worker. No "connect" tabs, no welcome pages. Agents work in tabs you already have open.

  • Secure by default. Agents only see tabs you grant, passwords are redacted, banking sites are blocked, uploads need your OK, and a killswitch stops everything. See Security.

  • Works everywhere a page does. Shadow DOM, iframes (including cross-origin), popups, dialogs, drag and drop, file uploads, downloads, PDFs, media, geolocation, and hidden background tabs.

Driver speed vs Playwright MCP

Real measurements from npm run bench on the same local pages, same machine (AMD Ryzen 5 5500), same MCP stdio transport, both headless. Median of 7 runs; no model is involved. Full method: store/BENCHMARK.md.

Flow (local test page)

Luculent Browser Driver

Playwright MCP 0.0.85

7-action sign-up form, all steps in one call

131 ms

1,748 ms

Same form, one call per action

165 ms

1,748 ms

Same form in your Chrome tab, through the extension

177 ms

not supported

4-action search with a delayed result, one call

163 ms

1,115 ms

Data the agent reads for the form

0.8 KB

4.0 KB

Cold start, new server to first page

522 ms

774 ms

Related MCP server: Chrome MCP Control Center

Quickstart

Choose your setup based on what you need:

Scenario A: In-Browser Diagnostics & Testing (Zero Extra Software)

If you only want in-browser testing, install the extension from the Chrome Web Store. Open the extension popup on any tab to run Click Tests, Visual Checks, and Code Audits directly in Chrome. No relay, Node, or background processes required.

Scenario B: Driving Chrome with External AI Agents (Claude, Cursor, Codex, Gemini)

To let external AI agents control your browser tabs over MCP or HTTP, connect Chrome to the local agent relay:

  1. Install the Extension: From the Chrome Web Store (or load unpacked).

  2. Start the Relay:

    • Option 1 (Consumer / 1-Click — Recommended): Download and run the standalone Companion App (.exe / zip) directly from the extension popup or releases page. It packages the relay and portable runtime—zero terminal commands or manual Node installation needed.

    • Option 2 (Terminal Auto-Installer — for developers):

      • Windows (PowerShell):

        irm https://raw.githubusercontent.com/LuculentTechnology/luculent-browser-driver/main/scripts/install.ps1 | iex
      • macOS / Linux (Terminal):

        curl -fsSL https://raw.githubusercontent.com/LuculentTechnology/luculent-browser-driver/main/scripts/install.sh | bash
    • Option 3 (Existing Node / npx): npx luculent-browser-driver start

  3. Grant Tab: Open the extension icon on your target tab and click Let agents use this tab.

  4. Connect Agent: Point your agent's MCP config to http://127.0.0.1:47800/mcp.

If you want to hack on the driver source code directly:

git clone https://github.com/LuculentTechnology/luculent-browser-driver
cd luculent-browser-driver
npm install
node src/cli.mjs start

More detail, including the CLI flags and HTTP endpoints: QUICKSTART.md.

Connect your agent

Replace /path/to/luculent-browser-driver with your clone and lbd_... with your key.

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/path/to/luculent-browser-driver/src/cli.mjs", "mcp"],
      "env": { "LBD_KEY": "lbd_..." }
    }
  }
}

Codex CLI (~/.codex/config.toml), using the relay's Streamable HTTP endpoint:

[mcp_servers.browser]
url = "http://127.0.0.1:47800/mcp"
bearer_token_env_var = "LBD_KEY"

Gemini CLI (~/.gemini/settings.json):

{ "mcpServers": { "browser": { "httpUrl": "http://127.0.0.1:47800/mcp", "headers": { "Authorization": "Bearer ${LBD_KEY}" } } } }

Anything else (scripts, custom agents):

curl -s http://127.0.0.1:47800/v1/rpc -H "Authorization: Bearer $LBD_KEY" -H "content-type: application/json" \
  -d '{"method":"run","params":{"steps":[{"action":"navigate","url":"https://example.com"},{"action":"extract","target":"h1"}]}}'

When you click in the AI's tab

One setting, in the side panel and in Settings, decides what happens if you click, type or scroll in the tab an agent is driving:

  • Cowork (default). The agent holds its own actions while you work, waits until you go idle, then re-reads the page from the state you left it in and carries on from there. Use it to get the agent past a spot it keeps looping on. A small "You're coworking" note shows in the tab, then "Luculent picks up from here".

  • Pause. Your input pauses the task. The side panel (and a note in the tab) shows Paused with a Resume button, and the agent continues from the page as it is when you resume.

  • Disable window. Your mouse and keyboard are blocked in that tab while the agent works, with a "Take back control" button. The killswitch always works.

Agents can read or set it with browser_click_mode. It syncs with your Luculent account settings when you are signed in.

Plans are loose frameworks

browser_plan takes a framework for the next set of actions, not an exact script. Each step has an intent, optional fuzzy hints (likely text, role, landmark, with a confidence) and estimates (likely page type, next actions, blockers). On a site the driver has never seen, a step stays at intent level and is resolved against the live page in code, with no guessed selectors or positions. Partial matches are normal. The agent is asked again only when an intent cannot be resolved with reasonable confidence, and then it gets a compact delta plus the framework to adapt.

Security

Every control is enforced by the relay, and the browser-level ones again inside the extension, so a compromised or rogue relay still cannot reach tabs you did not grant. Change them in the extension's Settings page or with lbd policy set key=value; each API key can only be tightened further (scopes and per-key overrides).

Control

Default

Which tabs agents can use

Only tabs you grant (plus tabs and popups agents open themselves)

Killswitch

Popup button, Alt+Shift+K, or lbd kill. Detaches every tab and refuses all calls until you resume

Password fields

Blocked: values are redacted and agents cannot type into them

Banking, payment and crypto sites

Blocked (built-in list of about 50 sites, plus any *bank* / credit-union host)

Your own block list / allow list

Empty (an allow list limits agents to those sites only)

Read-only mode

Off (on = agents can navigate and read but not click, type or run scripts)

Running custom JavaScript (browser_eval)

Blocked (can be set to Ask me or Allow)

Cookies, site storage

Blocked

File uploads

Ask me each time (Chrome notification with Allow / Deny)

Submitting login, password or payment forms

Ask me

Downloads

Allowed (can be turned off)

Browser-internal pages (chrome://, other extensions)

Always blocked

Local files (file://)

Blocked

Incognito tabs

Blocked

Raw DevTools Protocol commands

Blocked

Rate limit

20 actions/second, 600/minute per key

Relay identity

The extension pins the relay it paired with and refuses impostors

Activity log

On: every action and refusal, viewable in the popup and with lbd audit (never typed text or passwords)

Network

Relay listens on 127.0.0.1 only, refuses browser-page origins and DNS-rebinding hosts; API keys stored hashed

Sensitive capabilities also need the matching API key scope: a key minted with the default scopes (read,act,tabs,headless) cannot upload, run JavaScript or read cookies even if Settings allow it. Add scopes such as upload, eval, cookies, storage, passwords, files or cdp with keys mint --scopes.

Agents get a clear "Blocked by your Luculent security settings" error when they hit a control, and are told not to work around it. Report vulnerabilities privately: see SECURITY.md.

Tools

browser_run (batched steps), browser_tabs, browser_snapshot, browser_navigate, browser_click, browser_type, browser_press, browser_hover, browser_scroll, browser_select, browser_check, browser_upload, browser_eval, browser_wait, browser_extract, browser_cookies, browser_storage, browser_downloads, browser_history, browser_dialog, browser_screenshot, browser_parallel, browser_headless. browser_run steps also cover drag, wheel, tables, media, PDFs, geolocation and permissions.

Targets: e12 (a ref from a snapshot), text=Sign in, role=button[name="Search"], label=Email, or CSS.

Tested on real sites

The broad suite (node harness/broad.mjs) runs 92 checks against public test sites (the-internet, UI Testing Playground, DemoQA, TodoMVC, Wikipedia, MDN, GitHub, Hacker News, CodePen and more) and local fixtures, through both headless Chrome and the extension. Results: harness/RESULTS.md.

FAQ

What is this banner?

Chrome sometimes shows a bar that says this extension "is debugging this browser." Chrome shows that bar for any extension that can control a window. It cannot be hidden. It only means an AI agent is allowed to control that window — not that your computer is being hacked, and not that anything is being sent off your machine. To stop it, press the killswitch in the popup (or Alt+Shift+K), or click Cancel on the banner.

Development

npx playwright install chromium   # browser for the tests
npm test                          # unit, security and end-to-end tests (headless + extension)
npm run bench -- --iters 7        # benchmark vs Playwright MCP
node harness/broad.mjs            # real-site suite (add --source extension to drive the extension)
npm run package                   # Chrome Web Store zip in dist/

See CONTRIBUTING.md. Licensed MIT.


Built by Luculent. Your SOPs, enforced in the AI agents and tools you already use. Join the beta at luculent.dev/beta

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to control local Chrome/Edge browser profiles through MCP, including tab groups, bounded DOM actions, observations, and optional encrypted credential use.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables an AI agent to read and operate the Chrome or Edge tabs you are already using — titles, URLs, text, HTML, screenshots, clicks, typing, scrolling, and tab management — via a browser extension and native messaging, without restarting the browser, switching profiles, or opening a debug port. It exposes these capabilities as 19 MCP tools, with access limited to explicitly shared tabs and hardened by per-tab, origin-bound grants plus domain allow/deny lists.
      2
      MIT