zen-browser

About

Anthropic's Claude in Chrome extension only works in Chromium browsers. Zen is built on Firefox, so this project rebuilds the same idea for Firefox-based browsers. A small extension runs inside Zen, a local bridge connects it to Claude Code, and Claude Code gets a set of zen-browser tools that work on the tabs you're already signed in to.

Related MCP server: firefox-mcp

Features

• Full browser control. Open and switch tabs, navigate, click, type, press keys, scroll, hover, and fill forms. It works with React and Vue apps and inside shadow DOM.

• Sees the page the way Claude needs it. It gives Claude an accessibility-style page tree with element references, a text search, readable page text, and screenshots that are scaled so the click coordinates line up.

• Developer tools. It can run JavaScript in the page and read console output and network requests.

• You can see what it's doing. While Claude works in a tab, the tab glows, a cursor dot shows each action, and a Stop button pauses Claude right away.

• Live activity popup. The popup shows your connected Claude Code sessions and every action as it happens, and has a single switch that pauses everything.

• Several sessions at once. Each Claude Code session gets its own connection, and all of them share the same browser.

• Locked down. Everything stays on your machine. The extension and the bridge both have to prove they hold your private pairing key before either side will trust the other.

Getting started

Prerequisites

• Zen browser. It also works in Firefox Developer Edition, Nightly, or ESR (see Limitations).

• Claude Code

• Node.js 18 or newer

• Git

Installation

1. Install the bridge and connect it to Claude Code

git clone https://github.com/grapedjuice/claude-for-zen.git
cd claude-for-zen
npm install
npm run setup

npm run setup registers the zen-browser MCP server with Claude Code for every project. It also prints your pairing key, which you'll need in step 3.

2. Install the extension in Zen

The extension isn't on the Mozilla add-ons store, so Zen has to be told to accept it:

1. Open about:config in Zen, accept the warning, and set xpinstall.signatures.required to false.

2. Download claude-for-zen.xpi from the latest release.

3. Open about:addons, click the gear icon, choose Install Add-on From File…, and pick the downloaded .xpi.

4. Optional: right-click the toolbar, choose Customize Toolbar, and pin the ✷ button.

3. Pair them

Click the ✷ button in Zen, paste the pairing key from step 1, and click Pair. To see the key again, run npm run pair in the claude-for-zen folder.

4. Restart Claude Code

Open a new Claude Code session. The popup should say Connected to 1 Claude Code session.

Updating

cd claude-for-zen
git pull
npm install

Then download the latest .xpi and install it over the old one. Your pairing carries over.

Uninstalling

claude mcp remove --scope user zen-browser

Remove the extension from about:addons, delete the claude-for-zen folder, and delete ~/.claude-for-zen (which holds the pairing key). If you want signature checks back on, set xpinstall.signatures.required to true again.

Usage

Ask Claude Code to do things in the browser in plain language:

> open my GitHub notifications in Zen and summarize what needs my attention
> fill out the sign-up form on localhost:3000 with test data and tell me what breaks
> check the console on the current tab for errors and find the cause in this repo
> compare the prices on these three open tabs

Claude starts by listing your tabs, then reads pages and acts on elements by reference. It takes screenshots when the layout matters.

• Pause or stop. Click Stop on the in-page bar, or turn off the switch in the popup. Claude gets a clear "paused" error until you turn it back on.

• Choose the tab. Claude acts on whatever tab you tell it to. If you don't name one, it uses the active tab in the focused window.

Tools

How it works

Claude Code ──MCP over stdio──▶ bridge (server/index.js) ◀──WebSocket on 127.0.0.1:47321–47330──▶ Zen extension ──▶ your tabs

• The bridge. Claude Code starts one bridge per session. Each bridge takes the first free port between 47321 and 47330.

• The extension. It checks those ports, connects to every bridge it finds, and carries out the tool calls.

• Why not native messaging? Chrome extensions normally talk to Claude through native messaging. Here, the bridge is the process Claude Code launches, so a localhost socket with mutual authentication is simpler and works the same way on Windows, macOS, and Linux.

Security

• Mutual authentication. The bridge and the extension each prove they hold the pairing key with an HMAC-SHA256 challenge–response that uses fresh nonces in both directions. The extension ignores commands from any bridge that can't prove the key. The bridge drops any extension that can't, within 5 seconds. Other extensions, other local programs, and other users on the same machine can't pose as either side.

• The key stays private. It lives in ~/.claude-for-zen/pairing-key, inside your user profile.

• Websites can't reach it. The bridge listens on 127.0.0.1 only. It accepts WebSocket connections only from moz-extension:// origins with a loopback Host header, which blocks DNS-rebinding tricks. Its HTTP probe returns only {bridge, version}.

• Page scripts can't change settings. Pairing and settings can only be changed from the popup. Code running in the page, including code from the javascript tool, can only press Stop.

• Passwords are masked. read_page shows password fields as ••••.

• Nothing leaves your machine except through Claude Code. The extension only talks to localhost. What Claude reads is sent to Anthropic through Claude Code, as with any other tool output.

• Page content is untrusted. A web page can contain text written to manipulate an AI (prompt injection). Claude is told to treat page content as data, not instructions. Still, keep an eye on what it does on sites you don't trust, and use Stop if anything looks off.

Limitations

• Synthesized input. Firefox has no chrome.debugger API, so clicks and keys are generated inside the page and have event.isTrusted = false. Most sites don't care, but some captchas and anti-bot checks ignore this kind of input.

• Native dropdowns. <select> dropdowns can't be opened by clicking. Claude uses form_input for them instead.

• Iframes. The extension only works in a page's top-level frame, so it can't type into fields inside iframes.

• Browser pages. about: pages and addons.mozilla.org are off-limits to all extensions.

• Console capture. Capture starts while a Claude Code session is connected. For tabs that were opened before that, reload the tab to capture its logs.

• Firefox release builds. Regular Firefox ignores xpinstall.signatures.required. In release Firefox, load the extension temporarily from about:debugging (it's removed when the browser restarts), or use Developer Edition, Nightly, or ESR.

Troubleshooting

• Restart Claude Code after running npm run setup.

• Run claude mcp list and check that zen-browser shows Connected.

• Make sure nothing else is using all of ports 47321–47330.

Run npm run pair in the claude-for-zen folder and paste the key into the popup. If you deleted ~/.claude-for-zen, a new key was created and you need to pair again.

xpinstall.signatures.required is still true. Set it to false in about:config and try again.

The browser can't capture a minimized window. Claude brings the window forward and tries again, but if Zen stays minimized the capture fails.

npm run setup registers the bridge for every project, so each open Claude Code session connects. To limit it to certain projects, see the tip in Installation.

Development

extension/        Firefox WebExtension (Manifest V2)
  background.js   connections, pairing, tool dispatch, screenshots, network log
  content.js      page reading, synthetic input, in-page overlay
  console-hook.js console capture, registered only while a session is connected
  popup/          toolbar popup
server/index.js   MCP server + localhost WebSocket bridge
scripts/setup.mjs one-time setup (register + pair)

npm install
npm run lint           # web-ext lint
npm run build          # writes dist/claude-for-zen.xpi

To try local changes, load extension/manifest.json from about:debugging#/runtime/this-firefox → Load Temporary Add-on.

Contributing

Issues and pull requests are welcome.

1. Fork the repo and create a branch: git checkout -b fix/something

2. Make your change, run npm run lint, and try it in Zen.

3. Commit and open a pull request that describes what changed and how you tested it.

License

Distributed under the MIT License. See LICENSE for details.