Quickstart

From zero to an agent driving a tab in about five minutes.

You need Bun and a Chromium-based browser (Chrome, Brave, Edge, Chromium). Browspark is developed on macOS; the companion runs anywhere Bun does.

Option 1: one command

The setup script downloads the extension to ~/browspark-extension, registers the companion with the agents you pick (Claude Code, Codex, OpenCode, Cursor, Kilo, Antigravity), and prints the pairing steps. Add --test for a dry run that downloads nothing and writes no config.

curl -fsSL https://browspark.krishm.dev/setup.sh | bash

Then continue from Load the extension below.

Option 2: by hand

1. Get the extension

   Download browspark-extension.zip from the latest release and unzip it anywhere. To build it yourself instead:

   git clone https://github.com/uncaughterrs/browspark.git
   cd browspark
   bun install && bun run build
   

   That bundles the extension into the extension/ folder. The companion itself comes from npm, so the clone is only for the extension.

2. Load the extension

   Open chrome://extensions, switch on Developer mode, click Load unpacked and pick the unzipped folder (or extension/ in the clone). Pin the Browspark icon so the dashboard is one click away.

3. Register the companion with your agent

   For Claude Code:

   claude mcp add --transport stdio --scope user browspark -- bunx browspark-mcp@latest
   

   Every other client is covered in Connect an agent. The dashboard’s Overview page shows ready-to-copy snippets for each.

4. Pair once

   Ask the agent to call browser_status. While the extension is not connected it prints the pairing token and port. Open the dashboard (click the extension icon), go to Settings, paste the token and click Connect. The token lives in ~/.browspark/token and never changes unless you delete that file.

5. Share a tab

   In the dashboard’s Tabs page, share the tab the agent should work on, or switch on Share everything to include every current and future tab. Then ask:

   Open example.com in my browser, take a snapshot, and tell me what the headline says.

   The agent opens an ordinary tab in your current window, reads the accessible tree, and answers.

What you will see

• A “Browspark started debugging this browser” bar on shared tabs while the agent is attached. It is Chromium’s own notice for the debugger API and detaches after 30 seconds of inactivity. How to hide it.
• Tabs the agent opens are ordinary tabs in your window. They are shared automatically and become that agent’s default target.
• The dashboard’s Overview counts operations and errors only when the activity log is on. It is off by default.

Tell the agent what you want in plain language. The tool descriptions steer it: it calls browser_status first when something fails, re-snapshots after navigation, and does not open a separate browser unless a capability needs one.