theseus/DESIGN-claude-connector.md

Claude connector — design and plan

An opt-in MCP server built into Theseus, so a Claude client on the same computer (Claude Code, Claude Desktop) can work inside the user's real, signed-in profile: open a tab, read it, click, type, paste rich text into an editor, upload a file.

Why

On 2026-10-22 a Claude Code session had to paste a prepared story into a Medium draft as the user's author account. The Claude desktop app's built-in browser could not do it: its synthetic paste arrived empty and its typed text never reached Medium's editor. The two other routes are worse:

• --remote-debugging-port on the main profile opens a browser-wide DevTools port. Any local process can attach and read every tab, cookie and session.
• Theseus is a desktop app, and these sessions have no computer-use access to drive it from outside.

So the browser itself has to offer a narrow, user-controlled door.

Shape

A built-in add-on, bundled-addons/claude-connector/, following the Pithos pattern: activate(api) starts a small HTTP server on 127.0.0.1 from the main process and registers a sidebar panel. What it needs from the browser that no add-on API offered yet comes through one new host capability, tab-control, which only built-in add-ons can hold.

Claude Code ──HTTP (Bearer token)──► 127.0.0.1:<port>/mcp ─┐
Claude Desktop ─stdio─► stdio-shim.cjs ──HTTP──────────────┤
                                                           ▼
                                    claude-connector add-on (main process)
                                      policy: allowlist · password guard · upload folders · log
                                                           │ api.tabControl (tab-control capability)
                                                           ▼
                                    main.js: tabs, open/close/navigate, indicator
                                                           │ webContents.debugger (CDP, per tab)
                                                           ▼
                                                    one tab's page

Off by default

• The add-on ships with "defaultEnabled": false. main.js puts any built-in add-on with that flag into settings.disabledAddons the first time it sees it (remembered in settings.addonsDefaultOffSeen, so the user's later choice is never overridden). The user turns it on in Settings › Extensions › Claude connector.
• While it is off, nothing listens. When it is on, the panel has a second switch, Accept connections, on by default once the extension is turned on, so the stop button can close the port without uninstalling anything.

Transport and authentication

• MCP Streamable HTTP at http://127.0.0.1:<port>/mcp. POST carries JSON-RPC; GET opens an SSE stream (kept alive with comments, used as the "connected" signal); DELETE ends a session.
• Binds 127.0.0.1 only. The port is picked once per install (first free in 47800–47899, else any) and kept, so the config the user pasted stays valid.
• A random 256-bit token per install, base64url. Every request needs Authorization: Bearer <token>, compared in constant time.
• DNS-rebinding and browser guard: the Host header must be 127.0.0.1:<port> or localhost:<port>, and any request carrying an Origin header is refused. A web page cannot reach the server even if it guessed the token.
• Revoke in the panel issues a new token, which drops every client at once. Stop (toolbar chip or panel) closes the port.
• Claude Desktop speaks stdio, so the add-on ships stdio-shim.cjs, run by the Theseus executable itself in Node mode (ELECTRON_RUN_AS_NODE=1, the same mode the extension sandbox already uses). It reads the port from extensions-data/claude-connector/endpoint.json and the token from THESEUS_MCP_TOKEN, and relays line-delimited JSON-RPC to the HTTP endpoint.

Per-tab control, no browser-wide port

• Each controlled tab gets webContents.debugger (CDP 1.3) attached on its own webContents. No --remote-debugging-port, no DevTools target list.
• main.js already attaches that debugger to freeze background tabs (setTabFrozen). The connector shares the attachment: it attaches only if nothing is attached, and detaches only what it attached itself.
• Only ordinary web tabs (http:, https:) are controllable. Settings, add-on pages, the home page, file: and internal schemes are refused: a Settings tab would let a client switch the connector's own safety settings.
• A dormant restored tab is loaded and a frozen one thawed before it is used. While a tab is controlled it gets focus emulation (Emulation. setFocusEmulationEnabled), so editors that check document.hasFocus() accept input while the Theseus window is in the background.

Host capability tab-control (addons-host.js + main.js)

api.tabControl, built-in add-ons only, manifest must declare tab-control:

call	does
list()	every tab: id, title, url, kind (web/settings/addon/home), active, pending
webContents(id)	the tab's webContents, after loading a dormant tab and thawing a frozen one; throws for non-web tabs
open(url, {background})	new tab through main's own createTab (so BCNR names resolve as typed)
navigate(id, url)	main's navigateTab
close(id), activate(id)	as the tab strip does
setStatus({connected, clients, busy, tabIds})	drives the toolbar indicator and the per-tab marker
onStop(cb)	the indicator's stop button

Indicator

• A chip in the toolbar, next to Downloads: Claude with a dot that pulses while a tool call runs. Visible whenever a client is connected (an SSE stream is open or a request arrived in the last 2 minutes). Clicking it opens the connector panel; its ✕ stops the connector at once (closes the port, ends sessions, detaches every debugger).
• Each tab the client is controlling gets an outline marker in the tab strip.

Tools

tool	how
list_tabs	tabControl.list(); tabs on sites not yet approved show only their host
open_tab(url, background?)	approval for the target origin first
navigate(tab_id, url | action)	url, or back/forward/reload
close_tab(tab_id), activate_tab(tab_id)
screenshot(tab_id, full_page?)	Page.captureScreenshot, scaled to CSS pixels so coordinates match click(x, y); a hidden tab is brought to the front first (hidden views render no frames)
read_page_text(tab_id, max_chars?)	innerText read in an isolated world
snapshot(tab_id, interactive_only?)	Accessibility.getFullAXTree, compacted to role "name" [ref=eN] lines; refs map to backendDOMNodeId
click(tab_id, ref | x,y)	DOM.scrollIntoViewIfNeeded + DOM.getContentQuads, then Input.dispatchMouseEvent press/release
type(tab_id, text, ref?)	DOM.focus, then Input.insertText per line and a real Enter (Input.dispatchKeyEvent) between lines; mode: "keys" sends every character as keyDown/keyUp
press_key(tab_id, key, modifiers?)	Enter, Tab, Backspace, arrows, ctrl+a …
paste_html(tab_id, html, ref?), paste_text(tab_id, text, ref?)	write the real clipboard (clipboard.write({html, text})), webContents.paste(), then put the user's clipboard back
upload_file(tab_id, ref, path)	DOM.setFileInputFiles on an <input type=file>
wait_for(tab_id, selector | text, timeout_ms?)	polls in an isolated world
evaluate(tab_id, expression)	Runtime.evaluate in the page; listed only while Allow evaluate is on (off by default)

Page reads run in an isolated world (Page.createIsolatedWorld), so page scripts can neither see them nor tamper with the helpers.

Safety

• Per-site allowlist. The first time a client acts on an origin (opens it, navigates to it, reads or drives a tab on it), Theseus asks: Allow Claude to control medium.com? — Allow (remembered), This session only, or Don't allow. A refusal is remembered for 10 minutes, so a client cannot spam the prompt. The panel lists approved sites with a remove button.
• Never types into password fields. Before type, press_key, paste_* and evaluate-free input, the focused element (followed into shadow roots and same-origin frames) is checked in an isolated world: input[type=password], autocomplete=current-password|new-password| one-time-code, or a cross-origin frame that cannot be inspected → refused. click on a ref that is a password field is refused too, so a client cannot focus one by ref and then type.
• Upload folders. upload_file resolves the real path (symlinks and junctions followed) and refuses anything outside the folders the user added in the panel (none by default), anything that is not a regular file, and files over 100 MB. The ref must be an <input type=file>.
• evaluate is a separate switch, off by default, with a warning in the panel: it runs arbitrary script as the page.
• Action log. Every call is logged with an ISO timestamp, the tool, the tab's origin, a short summary of the arguments (typed and pasted text is logged by length and first 60 characters) and the outcome. The panel shows the newest entries live; the log is kept in extensions-data/claude-connector/actions.log (JSON lines, rotated at 1 MB).

What it does not defend against

• A program already running as the user. The token sits in the add-on store (extensions-data/claude-connector.json) next to the profile's cookies, which such a program can read anyway. The connector keeps the door shut to web pages and to other machines, and keeps the user in charge of which sites a connected client may touch.
• A site that changes a field's type after the focus check. The check runs right before each input; what the page does in between is up to the page.

Files

• bundled-addons/claude-connector/ — addon.json, index.js (activate, settings, panel messages), lib/mcp-server.cjs (HTTP + JSON-RPC + sessions), lib/tab-driver.cjs (CDP per tab), lib/tools.cjs (tool definitions and handlers), lib/policy.cjs (allowlist, upload paths, password guard script), lib/action-log.cjs, panel.html, stdio-shim.cjs, README.md.
• addons-host.js — tab-control capability and api.tabControl.
• main.js — the tabControl hook, indicator state, defaultEnabled:false handling, claude-connector kept as a reserved first-party id.
• preload.js, chrome.html — the indicator chip and the tab marker.
• tests/claude-connector.test.mjs — launches Theseus on a scratch profile (THESEUS_USER_DATA, THESEUS_NO_UPDATE_CHECK), with the connector pre-enabled in that profile, and drives a local test page over MCP: type into a rich editor, paste HTML with headings and links, upload a PNG, refuse a password field and an upload outside the folder.
• tests/claude-connector-unit.test.mjs — protocol, auth and policy checks that run under plain Node.
• README section with the claude mcp add command.

Steps

1. Host: tab-control capability in addons-host.js; hook, indicator state, default-off handling in main.js; chip in chrome.html/preload.js.
2. Add-on: server, driver, tools, policy, log, panel, shim.
3. Tests: unit (plain Node), then the Electron end-to-end test.
4. Docs: README section, add-on README.

Not in this round

• Cross-origin iframes (OOPIFs) are not driven; typing into one is refused because its focused element cannot be checked.
• No per-tool approval prompts beyond the per-site one.
• No remote (non-loopback) clients, by design.