Konnect

A local browser-automation bridge that lets AI agents drive your real browser — your actual login sessions, cookies, and tabs — instead of a cloud sandbox or headless instance. Konnect connects MCP-compatible coding agents (and a token-cheap CLI) to Comet Browser via a long-lived daemon and a Chrome MV3 extension.

Status: production. Runs on macOS via launchd (port 9223).

Architecture

A persistent aiohttp daemon (daemon/, listens on :9223) owns the WebSocket to a Chrome MV3 extension (extension/) that performs the actual page interaction; the WS survives MV3 service-worker eviction via an offscreen document. Two thin clients front the daemon's HTTP API: an MCP stdio shim (mcp/) for AI agents and a CLI (cli/) for low-token coding. The daemon is the single source of truth — MCP is one client, not the only interface.

See ARCHITECTURE.md for full design rationale and the decision tree (why daemon-over-MCP, why snapshot-first, why CLI+SKILL alongside MCP).

Components

konnect/
├── daemon/      # aiohttp daemon: /command /ws /health (the persistent core)
├── extension/   # Chrome MV3 extension (service worker + content script + offscreen WS)
├── mcp/         # MCP stdio server — thin shim → daemon HTTP
├── cli/         # argparse CLI → daemon HTTP (token-cheap)
├── skill/       # SKILL.md — agent operating instructions
├── tests/       # isolated test harness (disposable Chromium + CDP)
├── deploy/      # launchd plist template + install.sh
└── docs/        # operations notes

Install

# 1. Python deps (aiohttp for the daemon)
pip install -e .

# 2. Install + start the daemon under launchd
deploy/install.sh

# 3. Load the extension (one-time, manual)
#    chrome://extensions (or comet://extensions) → Developer mode → Load unpacked
#    → choose this repo's extension/ directory

deploy/install.sh auto-detects a Python with aiohttp (or takes an explicit path: deploy/install.sh /path/to/python). It renders local.konnect.daemon.plist with your $HOME and repo path — no hardcoded user paths.

Verify the daemon sees the extension:

curl http://127.0.0.1:9223/health   # → {"extension_connected": true}

Logs: /tmp/konnect-daemon.log. Stop: launchctl unload ~/Library/LaunchAgents/local.konnect.daemon.plist.

Usage — MCP tools

Wire mcp/konnect_mcp.py as an MCP server in your agent (Claude, Cursor, opencode). Exposed tools (all proxy to the daemon over HTTP):

Tool	Purpose
konnect_health	Check daemon + extension connection
konnect_list_tabs	List open browser tabs (group + blocked state)
konnect_find_tab	Select an already-open tab by URL prefix
konnect_navigate	Open a URL (new background tab by default)
konnect_snapshot	AX-style accessibility tree with ref=N targeting
konnect_click	Click an element by ref
konnect_fill	Fill an input/textarea/select/contenteditable by ref
konnect_screenshot	Capture tab/element to a PNG file (read via Read)
konnect_get_text	Visible text of the current tab
konnect_evaluate	Run JS in the page main world (fallback for ref limits)

Targeting is snapshot-first: call konnect_snapshot, read the ref=N tags, then konnect_click/konnect_fill by ref. Screenshots write to disk and are read with Read — never base64 into context.

Security

• Bearer-token auth (extension/token.json), generated by the daemon; tokens are git-ignored and never committed.
• evaluate runs in the MAIN world for trusted local use only. Sites that check event.isTrusted may reject synthetic events — a product boundary, not a bug.

License

MIT. Clean-room implementation; see ARCHITECTURE.md.