Requirements

A desktop Chromium browser, version 116 or newer: Chrome, Edge, Brave, Arc, Vivaldi.
Node 18 or newer, for the clone-and-install step and for the MCP server if you connect an agent.
An API key for one model provider, for the side panel. Coding agents can skip this if you configure a decision model instead.
git, or a zip of the repository. Nothing else: the extension is plain ES modules with no build step.

What you are installing

One unpacked extension, plus a Node process that only runs while your MCP client is open. There is no background service on your machine beyond Chrome's own extension host.

1 · Load the extension

Clone the repository and install the workspace. The install is only needed for the MCP server package; the extension folder itself has no dependencies.

Clone and install

git clone https://github.com/Shyamnath-Sankar/project-hailbrowser.git
cd project-hailbrowser
npm install

Then load the folder Chrome-style:

Open chrome://extensions.
Turn on Developer mode, top right.
Click Load unpacked and pick the extension/ folder inside your checkout. Pick the folder itself, not a file inside it.

The toolbar icon opens the side panel. Alt+H does the same from the keyboard. Pin the icon if you plan to use it daily; Chrome hides new extensions behind the puzzle menu otherwise.

2 · Add a model key

Open the side panel, then Settings. HailBrowser talks to any provider you already pay for, and to local runtimes that need no key at all.

Provider	Key needed	Notes
Anthropic	Yes	Claude models, tool calling.
OpenAI, OpenRouter, Together, Groq, DeepSeek	Yes	Any OpenAI-compatible endpoint works.
Google Gemini	Yes	Fast models suit long task loops.
Ollama, LM Studio	No	Local. For Ollama start it with `OLLAMA_ORIGINS=chrome-extension://*`, otherwise the extension gets a 403.

Keys are stored in chrome.storage.local and sent only to the provider you selected. There is no HailBrowser server in the middle, and no telemetry.

3 · Verify it works

Open any normal page, open the panel, and ask something that needs the page:

What does this page say it costs, and is there a cheaper plan below?

A working install answers from the page and shows the tool calls it made. If the panel answers without touching the page, the model is running but the extension is not attached; check that the tab is a normal https:// page and not a chrome:// one.

Two more checks worth doing once:

Alt+H opens the panel from the keyboard.
Settings → Safety has Allow external agents on if you plan to connect a coding agent.

4 · Connect an agent (optional)

If you want Claude Code, OpenCode, Cursor, Codex, Windsurf, Gemini CLI or Claude Desktop to drive the browser, print the config with your real checkout path:

Print every client config

npm run setup

Paste the block for your client, restart it, and look for a green MCP connected label in the side panel header. The details per client are on connect an agent.

5 · Update and uninstall

Pull the repository, then press the reload arrow on the HailBrowser card in chrome://extensions. Reinstalling from a different folder changes the extension ID, which the MCP server treats as a new extension: run npx hailbrowser-mcp trust <new id>, or npx hailbrowser-mcp trust --reset.

To remove it: click Remove on the extension card, and delete the MCP entry from your client config. Chats, tasks and reports live in chrome.storage.local and go with the extension.

Troubleshooting

Symptom	Cause and fix
The panel says the extension is not connected	Open Chrome, check the panel's MCP label, click the pill to retry, and make sure the hub port matches in both places.
Port already in use	Something else owns 12306. Pick another port with `--port` and set the same port in Settings.
Ollama returns 403	Start Ollama with `OLLAMA_ORIGINS=chrome-extension://*`.
Chrome blocks the page	`chrome://` pages and the Chrome Web Store cannot be automated. Navigate to a normal site.
A yellow "started debugging this browser" bar	Chrome showing that `chrome.debugger` is attached. It is expected and disappears when the tab closes or the extension reloads.
The agent clicks the wrong thing	Re-read the page first. Refs go stale after a navigation; `read_page` again instead of reusing an old `ref_N`.