⚡ MEXX-Browser-Agent (v3.0)

The High-Performance Autonomous Browser Agent & Execution Runtime. Give AI agents access to your authentic, daily-driver Chrome — without stealing cursor focus, leaking tokens, or bypassing security controls.

Unlike traditional headless browser automations (which spin up isolated, cold, unauthenticated instances that break 2FA and consume gigabytes of RAM), MEXX-Browser-Agent operates as a high-performance Local Browser Runtime: It connects AI agents (via Model Context Protocol, WebSocket, or REST) directly to your existing Google Chrome browser. Agents can inspect reactive DOM events, extract WebGL/WebGPU canvases directly from VRAM, record and replay deterministic workflows, and automate multiple background tabs in parallel — while you continue typing, coding, and browsing in the same window without cursor theft or window disruption.

🌟 Why MEXX v3.0?

* Design targets measured with the local harness — reproduce via npm run benchmark (see benchmark/). Actual figures depend on machine, page, and workload; verify on your setup before quoting.

Related MCP server: byob

🏛️ Core Architecture Pillars

MEXX v3.0 is built on a clean separation of concerns:
AI decides Intent → Policy controls Permissions → Deterministic Engine executes.

flowchart TD
    subgraph AgentLayer ["AI Agent Layer (Gehirn)"]
        Agent["Antigravity / Claude Desktop / Cursor / MCP Client"]
    end

    subgraph MEXXRuntime ["MEXX v3.0 Runtime (:8910 / :8911)"]
        direction TB
        ZeroTrust["Zero-Trust Security Gate (256-bit Token + Origin Check)"]
        Policy["Security Firewall (R0–R4 Classification & Invariant Enforcement)"]
        WorldState["Shared Semantic World State (Revisions, Leases, 50-Token Diff)"]
        EventEngine["Event-Driven Sleep/Wake (DOM Mutation Matcher)"]
        WorkflowEngine["Deterministic Workflow Runner & Self-Healing Engine"]
        
        ZeroTrust --> Policy
        Policy --> WorldState
        Policy --> EventEngine
        Policy --> WorkflowEngine
    end

    subgraph ChromeLayer ["Daily-Driver Google Chrome"]
        direction TB
        ExtWorker["Extension Service Worker (MV3)"]
        BackgroundTabs["Silent Background Tabs (CDP Shadow Execution)"]
        ForegroundTab["User Active Tab (Zero-Focus Coexistence)"]
        
        ExtWorker <--> BackgroundTabs
        ExtWorker <--> ForegroundTab
    end

    Agent <==>|MCP / WebSocket / REST| ZeroTrust
    WorkflowEngine <==>|Fast CDP / DOM Pipeline| ExtWorker

🚀 Key Innovations in v3.0

1. Event-Driven Sleep/Wake Engine (browser_wait_for_event)

• Zero Token Cost While Waiting: Agents no longer poll in busy loops. Calling browser_wait_for_event suspends the agent asynchronously until the target condition occurs.

• In-Browser Matching: Monitored directly inside Chrome's content.js with microtask batching (queueMicrotask) and 150ms anti-flapping stabilization.

• Supported Events: DOM_APPEAR, DOM_CHANGE, TEXT_MATCH, NAVIGATE, DOWNLOAD_COMPLETE.

2. Shared Semantic World State (browser_get_world_state)

• Context Compression (~50 vs. ~50,000 tokens): Extracts concise semantic snapshots per tab: modal status, authentication state, dirty forms, active alerts, and primary CTAs.

• Differential Queries (GET /world-state/:tabId/diff): Only streams high-level semantic deltas (MODAL_OPENED, FORM_DIRTY).

• Concurrency Leases (browser_acquire_lease): Multi-step critical operations obtain exclusive tab leases (ttlMs: 5000–60000) to prevent agent collisions.

• Human Precedence Guarantee: Any user interaction immediately revokes automated leases.

3. Behavior Memory & Deterministic Workflow Engine

• "Record first, parameterize second": Capture user browser flows once, parameterize variables dynamically (${email}, ${searchQuery}), and replay deterministically.

• Token-Free Replay (Zero LLM Calls): Runs in ~100–200 ms per step* without querying an LLM during execution.

• Multi-Signal Target Fingerprints: Elements are identified by a resilient cascade (TestID > ARIA > Name > Stable ID > Text Anchor > Semantic CSS with Tailwind entropy filtering).

• Levenshtein Tolerance (>0.75): Absorbs minor UI copy variations ("Rechnung herunterladen" vs. "Rechnung laden") without triggering healing failures.

• Anti-Poisoning Staged Repairs: Healed selectors are placed into stagedRepairs and only committed to immutable versions (version++) upon verification.

4. Hardened Security & Defense-in-Depth

• Deterministic Risk Classes (R0–R4):

  • R0: Read-only inspection (readTab, extractCanvas, getLiveContext).

  • R1: Passive navigation & non-destructive control (scroll, closeTab).

  • R2: State alterations & form submits (Policy-guided).

  • R3: Destructive mutations (delete, drop, cancel subscription). Mandatory Human Approval.

  • R4: High-risk domains (banking, crypto, payment gateways like Stripe/PayPal). Mandatory Human Approval.

• Ambiguity Hard-Stop: If self-healing detects multiple candidate matches (candidateCount > 1), autonomous guessing is strictly prohibited. Execution halts with HTTP 428 (ambiguous: true).

• Target Identity Binding (TOCTOU Protection): Re-validates target presence and visibility synchronously immediately prior to clicking or filling.

• Zero PII / Secret-Leak on Normal Inputs: Automatically detects API keys (sk_..., ghp_...), JWTs, Slack tokens, credit cards, and IBANs across all inputs and sanitizes disk storage.

• Anti-Collision Modal Protection: Modals containing financial or destructive signals (DESTRUCTIVE_KEYWORDS, FINANCIAL_KEYWORDS) override automatic interstitial dismissal and enforce human review.

🥊 Ecosystem Comparison: Where MEXX Stands

* Own figures: design targets, reproducible via npm run benchmark (see benchmark/). † Competitor figures are rough public estimates, not independently benchmarked by us. If you maintain one of these projects and a cell is wrong, please open an issue — corrections are welcome.

🛠️ MCP Tools Suite

Core tools at a glance (23 total) — full reference with risk notes in TOOLS.md:

⚖️ Known Limitations & Transparent Boundaries

To maintain high technical integrity, MEXX clearly communicates its operational boundaries:

1. Keyword Heuristics are Baseline Sensors, Not Complete Semantics:
   DESTRUCTIVE_KEYWORDS and FINANCIAL_KEYWORDS effectively catch common confirmation dialogues ("löschen", "delete", "buy", "order"). However, atypical wording (e.g., "Finalisieren", "Vorgang abschließen" on custom checkout steps) or icon-only buttons without text may not trigger keyword alerts. MEXX combines keywords with action semantics and structural modal detection, but does not claim 100% natural language comprehension without human oversight on unknown critical paths.

2. Test Suite Scope (93/93 Tests, 6 Suites):
   The 100% green test suite proves strict contract compliance, deterministic execution, and state machine integrity against comprehensive internal fixture suites and mocked scenarios. Real-world third-party websites exhibit immense DOM variance; wild adversarial edge cases are addressed through strict Fail-Closed mechanics.

3. Tab Lifecycle & Focus Invariant:
   The closeTab action is designed to clean up automated background tabs and prevent memory leaks. Automated workflows must verify tab ownership to prevent closing tabs where the user is actively working.

4. Anti-Detection & Bot Shields:
   MEXX is an assistive copilot inside your authentic desktop Chrome. It does not spoof hardware fingerprints or bypass anti-bot shields (Cloudflare Turnstile, Akamai).

🚀 1-Click Launch

Prerequisites: Node.js 20+ and a recent Google Chrome (MV3-capable, Chrome 88+) on Windows, macOS, or Linux.

Get up and running in one command:

# If cloned locally:
npm start

# Or with tool-named alias:
npm run copilot

# Or on a fresh machine — everything included (clone, install, build, launch):
git clone https://github.com/Jera1807/mexx-browser-agent.git && cd mexx-browser-agent && npm install && npm start

# (After the first npm publish, this becomes: npx mexx-browser-agent)

What this command handles automatically:

1. Generates Zero-Trust Token: Creates a cryptographically secure 256-bit session token (.bridge-token) synced directly into the extension bundle (token.json).

2. Auto-detects Chrome: Finds your local chrome.exe on Windows, macOS, or Linux.

3. Auto-loads Extension: Launches Chrome with --load-extension pre-configured.

4. Auto-configures MCP: Detects your claude_desktop_config.json and registers mexx-browser-agent as an active MCP tool.

5. Starts Live Bridge: Starts the high-speed WebSocket (:8910) and HTTP API (:8911) with strict origin verification.

🔒 Security Policy & Privacy

SECURITY.md documents the threat model, the deterministic R0–R4 risk classes, the human-approval flow (single-use tokens, TOCTOU binding), and the fail-closed invariants.

Privacy & telemetry: the extension sends nothing to external servers. All traffic stays on localhost (127.0.0.1:8910/:8911). The only data written to disk is local: the session token (.bridge-token), the append-only audit log (audit.jsonl), and recorded workflows (workflows.json) — all git-ignored by default. There is no analytics, no tracking, no cloud component.

🤝 Contributing

Issues and pull requests are welcome once the repository is public. Please run npm run release-check (build, audit, secret scan, full test suite) before submitting. Security vulnerabilities: see SECURITY.md for responsible disclosure.

📄 License

Apache-2.0 © Jerome Lichy — see LICENSE. The patent grant and retaliation clause protect contributors and users alike.