Browser Extension

Chrome extension that gives AI agents access to the user’s real browser — with existing cookies, sessions, and authentication. No bot detection, no Playwright sandboxes.

Why Use It

Playwright runs in an isolated browser with no cookies or login state. Many sites detect and block automated browsers. The browser extension bridges to the user’s real Chromium instance, so agents can:

• Navigate and interact with authenticated pages
• Use existing OAuth sessions (GitHub, Google, etc.)
• Bypass bot detection and CAPTCHAs
• Take screenshots of real page state

Architecture

Agent Worker
    ↓
BrowserExtTool (src/tools/browser-ext/)
    ↓
BrowserBridgeService (WebSocket)
    ↓ ws://localhost:3005/ws/browser-bridge
Chrome Extension
    ├─ Service Worker — WebSocket client, command dispatch
    ├─ Content Script — element highlighting
    └─ Popup — settings, connect/disconnect

Commands are sent as JSON over WebSocket with a unique ID. The extension executes the command and returns the result with the same ID.

Setup

1. Install Chromium

# Manjaro / Arch
sudo pacman -S chromium

# Ubuntu / Debian
sudo apt install chromium-browser

2. Load the Extension

1. Open chromium://extensions
2. Enable Developer mode (toggle, top right)
3. Click Load unpacked
4. Select the browser-extension/ directory

3. Configure & Connect

1. Click the extension icon in the toolbar
2. Enter the backend URL: ws://localhost:3005
3. Enter your API key (master key from .env)
4. Click Connect

The badge shows ON when connected, OFF when disconnected.

Alternatively, run the setup wizard (bun run setup) which can install the extension automatically.

Available Commands

Navigation & Tabs

Command	Description	Permission
navigate	Navigate active tab to a URL	ASK
new_tab	Open a new browser tab	ASK
close_tab	Close a tab by ID	ASK
select_tab	Switch focus to a tab by ID	ASK
get_tabs	List all open tabs	ALLOW

Screenshots & Content

Command	Description	Permission
screenshot	Capture visible tab as base64 PNG	ALLOW
extract_content	Extract text, links, forms from page	ALLOW

Interactions

Command	Description	Permission
click	Click element by CSS selector (supports double-click)	ASK
fill	Fill input field with value	ASK
select	Select option in a <select> element	ASK
hover	Hover over an element	ASK
press_key	Press a keyboard key (Enter, Tab, Escape, etc.)	ASK
scroll	Scroll the page or an element by pixel offset	ASK
drag	Drag an element from one position to another	ASK

Waiting & Debugging

Command	Description	Permission
wait_for	Wait for an element or condition to appear	ALLOW
highlight	Visually highlight an element on the page	ALLOW

JavaScript & State

Command	Description	Permission
evaluate	Execute JavaScript in page context	ASK (dangerous)
get_cookies / set_cookies	Read/write cookies for a domain	ASK (dangerous)
get_storage / set_storage	Read/write localStorage or sessionStorage	ASK (dangerous)

Monitoring

Command	Description	Permission
get_console	Retrieve captured console log entries	ALLOW
get_network	Retrieve captured network request/response log	ASK
handle_dialog	Accept or dismiss browser dialogs (alert, confirm, prompt)	ASK

Roles with Browser Extension

The browser-ext tool is available to these roles:

Role	Why
research	Browse authenticated sources
qa	Test real browser behavior
security	Assess authenticated endpoints
ai	Interact with AI platforms
general	Fallback access

Security

• WebSocket authenticated via master key
• evaluate, get_cookies, set_cookies, get_storage, set_storage, and get_network are marked as dangerous and require explicit permission approval
• Navigation and interaction commands require ASK-level approval
• Screenshots, content extraction, and console capture default to ALLOW
• v2.0.0 requires the tabs and cookies browser permissions