Chrome Browser Relay

Chrome Browser Relay lets the AI control your real Chrome browser — with your existing sessions, cookies, and logins intact. Unlike the built-in Browser tools (which open a clean Electron window), Chrome Relay operates on the Chrome you use every day.

How It Works

AI Chat → ChromeRelay tools → Alma Server → WebSocket → Chrome Extension → chrome.debugger → Your Tab

Alma ships with a Chrome extension that bridges your browser to the AI via the Chrome DevTools Protocol (CDP). The extension connects to Alma over a local WebSocket, and the AI sends commands like navigate, click, type, and screenshot through this channel.

Setup

Option 1: One-Click Launch (Recommended)

1. Open Alma → Settings → Chrome Relay
2. Copy the Auth Token displayed on the page
3. Click Launch Chrome with Extension
4. Wait for the Connection Status to turn green

WARNING

For best results, close all Chrome windows before clicking "Launch Chrome with Extension". The --load-extension flag works most reliably when Chrome is not already running.

Option 2: Manual Install

If one-click launch doesn't work (e.g., Chrome is already running):

1. Open Alma Settings → Chrome Relay
2. Expand the Manual Install section and copy the Extension Path
3. Open Chrome and navigate to chrome://extensions
4. Enable Developer mode (toggle in the top-right corner)
5. Click Load unpacked and paste the extension path
6. Click the extension icon in the Chrome toolbar to open the popup
7. If not auto-connected, click Settings in the popup footer
8. Enter the Port (23001 by default) and Auth Token from Alma
9. Click Save — the extension will reconnect automatically

Verifying the Connection

• The extension badge shows ON (green) when connected
• Alma Settings → Chrome Relay shows a green Connected status
• Attached tabs are listed in both the extension popup and Alma Settings

Available Tools

Tool	Description
ChromeRelayListTabs	List all open Chrome tabs with ID, URL, title, and active state
ChromeRelayNavigate	Navigate a tab to a URL, or create a new tab
ChromeRelayClick	Click an element by CSS selector (auto-scrolls into view)
ChromeRelayType	Type text into an input field, optionally press Enter
ChromeRelayScreenshot	Capture a screenshot for visual analysis
ChromeRelayRead	Read page content as Markdown (via Readability)
ChromeRelayReadDom	List all interactive elements (buttons, links, inputs) with selector hints
ChromeRelayEval	Execute JavaScript in the page context
ChromeRelayScroll	Scroll the page up or down
ChromeRelayBack	Navigate back in history
ChromeRelayForward	Navigate forward in history

Usage Examples

Browse with your login sessions

"Check my GitHub notifications"
"Open my Gmail and summarize the latest emails"
"Go to my Jira board and list the open tickets"

The AI uses your existing Chrome sessions, so you don't need to log in again.

Interact with pages

"Search for 'TypeScript best practices' on Google"
"Click the first search result"
"Fill in the contact form with my name and email"

Read and extract content

"Read the article in my current tab and summarize it"
"List all the links on this page"
"Take a screenshot of the page"

Chrome Relay vs Built-in Browser

	Chrome Relay	Built-in Browser
Browser	Your real Chrome	Electron window
Sessions/Cookies	Your existing logins	Clean session
Extension required	Yes	No
Use case	Tasks needing your accounts	General browsing

TIP

If you need to interact with a site where you're already logged in (Gmail, GitHub, Jira, etc.), use Chrome Relay. For general web browsing or research that doesn't need authentication, the built-in Browser tools work fine.

Settings

All Chrome Relay settings are in Settings → Chrome Relay:

Setting	Description
Connection Status	Shows whether the extension is connected
Auth Token	Token for authenticating the extension (copy, regenerate)
Launch Chrome	One-click button to start Chrome with the extension
Manual Install	Step-by-step instructions for manual setup
Attached Tabs	List of tabs with an active debugger session

Troubleshooting

Extension shows OFF (red badge)

• Verify Alma is running and port 23001 is available
• Check the Auth Token matches in both Alma Settings and extension Options
• Click Reconnect in the extension popup

"Launch Chrome with Extension" has no effect

• Close Chrome completely (including background processes) first
• On macOS, check Activity Monitor for lingering Chrome processes
• Fall back to the Manual Install method

AI doesn't use ChromeRelay tools

• Mention "my Chrome browser" or "my real browser" explicitly in your prompt
• The AI distinguishes between ChromeRelay (real Chrome) and Browser (Electron) based on context

Extension disconnects frequently

• Chrome may suspend the service worker; the extension uses keep-alive alarms to prevent this
• If the issue persists, check your network/firewall settings for localhost connections
• Try regenerating the Auth Token in Alma Settings

Token regenerated, extension disconnected

This is expected. After regenerating the token:

1. Open the extension popup → Settings
2. Enter the new token
3. Click Save