claude-chromium-native-messaging

Claude Native Messaging for Chromium Browsers

Use Claude AI browser extension with Brave, Arc, Vivaldi, Edge, Opera, Genspark, Helium, and other Chromium-based browsers

Enable Claude in Chrome extension to work with alternative Chromium-based browsers. Connect Claude Desktop and Claude Code to your favorite browser!

Quick Start

macOS / Linux:

git clone https://github.com/stolot0mt0m/claude-chromium-native-messaging.git
cd claude-chromium-native-messaging
./setup.sh

Windows (PowerShell):

git clone https://github.com/stolot0mt0m/claude-chromium-native-messaging.git
cd claude-chromium-native-messaging
.\setup.ps1

Linux Installation

On Linux, Claude Code CLI provides the native messaging host. This tool extends Claude Code’s browser support to additional Chromium browsers that Claude Code doesn’t configure automatically.

Prerequisites

• Claude Code CLI installed and set up
• Chrome, Chromium, Brave, or other Chromium browser installed

Option 1: Quick Setup (Recommended)

git clone https://github.com/stolot0mt0m/claude-chromium-native-messaging.git
cd claude-chromium-native-messaging
./install-linux.sh

This script:

1. Verifies Claude Code CLI is installed and its native host exists
2. Detects which alternative Chromium browsers are installed
3. Copies the native messaging manifest to each browser’s directory

Option 2: Interactive Setup

./setup.sh

The interactive setup lets you select specific browsers and provides more control.

How It Works on Linux

Claude Code CLI installs its native messaging host at ~/.claude/chrome/chrome-native-host and registers it for Google Chrome and Microsoft Edge. This tool copies that registration to additional browsers:

Claude Code CLI
    └── installs native host at ~/.claude/chrome/chrome-native-host
    └── registers for: Chrome, Edge (automatic)

This tool
    └── registers for: Brave, Vivaldi, Chromium, Opera, 25+ more browsers

After Installation

1. Completely quit your browser (check ps aux | grep chrome to verify no processes remain)
2. Restart the browser
3. Install the Claude extension if not already installed: Chrome Web Store
4. Open Claude in the side panel — it should now connect via Claude Code

More Help

See docs/linux-setup.md for detailed instructions and troubleshooting.

Features

• 27+ Supported Browsers - Brave, Arc, Vivaldi, Edge, Opera, and more
• Cross-Platform - Works on macOS, Linux, and Windows
• Safe by Default - Dry-run mode, backup support, and path validation
• Interactive Setup - Select which browsers to configure
• JSON Configuration - Easy to extend with new browsers
• Test Suite - Automated tests for reliability

The Problem

Claude’s official browser extension only supports Google Chrome. But many developers prefer browsers like Brave, Arc, Vivaldi, or Microsoft Edge.

The extension actually works fine in these browsers — it’s just the Native Messaging Host configuration that’s missing. Without it:

• Claude Desktop can’t connect to the browser extension
• Claude Code’s /chrome command doesn’t detect the extension
• No browser automation capabilities

The Solution

This tool automatically configures Native Messaging Host for your Chromium browser, enabling:

• Full Claude Desktop integration (macOS/Windows)
• Full Claude Code integration (all platforms)
• Claude Code browser automation (/chrome)
• Side panel functionality
• All Claude in Chrome features

Supported Browsers

All browsers listed below are Chromium-based and support the Chrome Extensions API including Native Messaging. The setup script auto-detects installed browsers and configures the necessary manifest files.

Confirmed Working

These browsers have been tested and confirmed working by users or maintainers:

Known Issues

These browsers work with native messaging but have known caveats:

Should Work (Chromium-based, not yet confirmed)

These are genuine Chromium/Blink-based browsers with full Chrome extension support. They should work based on their architecture, but haven’t been explicitly confirmed by users yet. If you use any of these browsers, please open an issue to let us know if it works!

Help us verify! If you successfully use this tool with any of the browsers above, please report it so we can move it to the confirmed list.

Not Compatible

Your browser not listed? The script supports custom paths — any Chromium-based browser with Chrome extension support should work.

Prerequisites

Before running the setup:

All platforms also need:

• Claude in Chrome extension installed in your browser (Chrome Web Store)
• Bash 4.0+ (macOS users may need to install via Homebrew: brew install bash)

Installation

macOS / Linux

# Clone the repository
git clone https://github.com/stolot0mt0m/claude-chromium-native-messaging.git
cd claude-chromium-native-messaging

# Run the interactive setup
./setup.sh

Windows

# Clone the repository
git clone https://github.com/stolot0mt0m/claude-chromium-native-messaging.git
cd claude-chromium-native-messaging

# Run the interactive setup
.\setup.ps1

The script will:

1. Detect installed Chromium browsers
2. Show which ones have the Claude extension
3. Let you select which browser(s) to configure
4. Create the necessary manifest files

Command Line Options

Examples

# Preview what would be changed (dry-run)
./setup.sh --dry-run

# Install with automatic backups
./setup.sh --backup

# Install for a specific browser path
./setup.sh --path ~/Library/Application\ Support/MyBrowser

# Uninstall with verbose output
./setup.sh --uninstall --verbose

Custom Browser Paths

If your browser stores its data in a non-standard location, use the --path / -Path flag to point the setup script directly at the browser’s data directory (not the executable).

The data directory is where the browser stores profiles, preferences, and extensions. Common locations:

macOS example — Chrome Canary:

./setup.sh --path "$HOME/Library/Application Support/Google/Chrome Canary"

Linux example — Chrome Canary (dev channel):

./setup.sh --path "$HOME/.config/google-chrome-unstable"

Windows example — Chrome Canary:

.\setup.ps1 -Path "$env:LOCALAPPDATA\Google\Chrome SxS\User Data"

Custom Chromium build:

# Point to wherever your Chromium stores its user data
./setup.sh --path "/opt/my-chromium/user-data"

Tip: To find your browser’s data directory, navigate to chrome://version in the address bar and look at the Profile Path. The data directory is the parent of the profile folder (e.g., if Profile Path is ~/.config/google-chrome-unstable/Default, the data directory is ~/.config/google-chrome-unstable).

Manual Setup

See the detailed Manual Setup Guide if you prefer to configure things yourself.

Verification

After running the setup:

1. Completely quit your browser (check Activity Monitor / Task Manager)
2. Restart the browser
3. Open Claude extension in the side panel
4. For Claude Code: Run /chrome in your terminal

How It Works

Chrome extensions communicate with native applications through the Native Messaging API. This requires JSON manifest files that tell the browser where to find the native host binary.

macOS / Windows

Linux

On Linux, Claude Code CLI provides the native messaging host. Claude Desktop is not available for Linux.

Claude Code automatically registers its native host for Google Chrome and Microsoft Edge. This tool extends that registration to additional Chromium browsers.

Manifest Locations

The script creates manifests in your browser’s data directory:

macOS:

~/Library/Application Support/YOUR_BROWSER/NativeMessagingHosts/

Linux:

~/.config/YOUR_BROWSER/NativeMessagingHosts/

Windows:

%LOCALAPPDATA%\YOUR_BROWSER\User Data\NativeMessagingHosts\

Project Structure

claude-chromium-native-messaging/
├── setup.sh                        # macOS/Linux interactive setup
├── setup.ps1                       # Windows setup
├── install-linux.sh                # Linux quick installer (extends Claude Code)
├── uninstall-linux.sh              # Linux uninstaller
├── config/
│   └── browsers.json               # Browser paths & extension IDs
├── tests/
│   ├── test_setup.sh               # Bash test suite (52 tests)
│   ├── test_browser_detection.sh   # Browser detection tests (76 tests)
│   ├── test_setup.ps1              # PowerShell tests
│   ├── setup.Tests.ps1             # Pester tests (Windows)
│   └── fixtures/                   # Test data files
├── docs/
│   ├── manual-setup.md             # Manual setup guide
│   └── linux-setup.md              # Linux-specific guide
├── CHANGELOG.md
├── CONTRIBUTING.md
├── TESTING.md                      # Test suite documentation
├── VERSION
├── LICENSE
└── README.md

Troubleshooting

Arc Browser Limitations

Arc does not implement Chrome’s chrome.sidePanel API. This means:

• Clicking the Claude extension icon in Arc’s toolbar does nothing — the side panel won’t open
• The extension can only be opened manually as a full tab: navigate to chrome-extension://fcoeoabgfenejglbffodgkkbkcdhcgfn/sidepanel.html
• In tab mode, the extension cannot orchestrate other tabs (no page reading, no browser automation, no screenshots of adjacent tabs) because the tab group context that Chrome’s side panel provides is missing
• Native messaging and Claude Desktop integration work normally

What works in Arc: Claude as a chat interface (ask questions, generate code, all AI features). What doesn’t work in Arc: Side panel integration, browser automation, tab orchestration.

Tip: You can pin the extension URL as a sidebar entry in Arc for quick access, or use Arc’s Split View to have the chat next to a webpage — but there is no cross-tab interaction.

Vivaldi Blank Side Panel

Native messaging installs correctly in Vivaldi on macOS, but clicking the Claude extension icon opens a blank side panel. This is a Vivaldi-specific bug — Vivaldi’s chrome.sidePanel API implementation does not render extension content. The extension itself is fully functional; it just can’t render through Vivaldi’s native side panel mechanism.

Confirmed workaround: use Vivaldi’s Web Panel

1. Navigate to the extension URL in a regular tab:

   chrome-extension://fcoeoabgfenejglbffodgkkbkcdhcgfn/sidepanel.html
   

2. Accept the beta disclaimer
3. Copy the URL from the address bar
4. In Vivaldi’s left sidebar, click + (Add Web Panel) and paste the URL
5. Claude now lives permanently in Vivaldi’s sidebar as a Web Panel

What works in Vivaldi: Full Claude interface, Claude Desktop native messaging, all AI features — via the Web Panel workaround above.

What doesn’t work: Opening Claude via the extension toolbar icon (the chrome.sidePanel API is broken in Vivaldi).

Chromium Snap on Linux

When Chromium is installed as a Snap package (default on Ubuntu), native messaging does not work due to Snap’s sandbox:

1. Wrong manifest path: The setup script writes to ~/.config/chromium/NativeMessagingHosts/, but Snap Chromium reads from ~/snap/chromium/common/chromium/NativeMessagingHosts/
2. Isolated /tmp: Snap runs Chromium with a private /tmp filesystem. The native messaging host socket in /tmp/claude-mcp-browser-bridge-<user>/ is invisible to the sandboxed browser — even if the manifest path is fixed, socket communication still fails.

Workaround: Use a non-Snap Chromium-based browser instead. Brave, Chrome, Edge, and other browsers installed via .deb/APT work without issues.

How to check if your Chromium is a Snap:

which chromium-browser && snap list chromium 2>/dev/null && echo "Snap detected — use a different browser"

Extension not connecting after restart

1. Make sure you completely quit the browser (not just closed windows)
2. Check Activity Monitor / Task Manager for remaining browser processes
3. Verify the extension ID is fcoeoabgfenejglbffodgkkbkcdhcgfn

Claude Code /chrome doesn’t work with non-Chrome browsers

This is a known limitation with a deeper cause than just process detection. Our technical analysis found that Claude Code’s /chrome MCP integration communicates through a remote WebSocket bridge (wss://bridge.claudeusercontent.com), not through local sockets. The Chrome extension connects to this bridge, Claude Code’s MCP server connects to the same bridge, and they are matched by user account.

The problem: the extension checks a server-side feature flag (chrome_ext_bridge_enabled) before connecting to the bridge. This flag currently returns false for non-Chrome browsers, which means the extension never opens the bridge WebSocket — so Claude Code’s MCP server can’t find it.

What this tool fixes: Native messaging manifests (extension ↔ native host communication). This enables the side panel, extension login, and Claude Desktop integration.

What this tool cannot fix: The /chrome MCP integration (browser automation via Claude Code). This requires Anthropic to unlock the bridge feature flag for non-Chrome browsers.

See Issue #34364 for the full technical analysis and Issue #18075 for the feature request.

Linux: Native host not found

Make sure Claude Code CLI is installed and has been run at least once:

npm install -g @anthropic-ai/claude-code
claude
# Then use /chrome inside Claude Code

The native host should appear at ~/.claude/chrome/chrome-native-host.

Bash version error on macOS

macOS ships with Bash 3.2. Install a newer version:

brew install bash
/opt/homebrew/bin/bash ./setup.sh

Permission errors (macOS/Linux)

chmod +x setup.sh
chmod 644 ~/Library/Application\ Support/YOUR_BROWSER/NativeMessagingHosts/*.json

Browser not detected

The setup script detects browsers by checking for data directories (not executables) and validating that they contain Chromium profile markers (e.g., a Default/ folder, Local State file, or Preferences file). If your browser is installed but not detected:

1. Verify the browser has been launched at least once — the data directory is only created after the first run
2. Check that the data directory exists — see Custom Browser Paths for expected locations
3. Use the custom path option to specify the data directory manually:

macOS/Linux:

./setup.sh --path "/path/to/your/browser/data"

Windows:

.\setup.ps1 -Path "C:\path\to\browser\User Data"

Tip: Use --dry-run --verbose to see exactly which paths the script checks and why a browser might be skipped.

FAQ

Why is my installed browser not showing up?

The setup script uses filesystem-based validation to detect browsers. It does not search for browser executables — instead, it looks for the browser’s data directory (where profiles and settings are stored) and checks for Chromium-specific markers like Default/, Local State, or Preferences.

A browser won’t be detected if:

• It has never been launched (the data directory is only created on first run)
• The data directory is in a non-standard location (e.g., installed via a different package manager)
• The data directory exists but is empty (incomplete installation)

Solution: Launch the browser at least once, then re-run the setup script. If the browser still isn’t detected, use the --path flag to specify the data directory manually (see Custom Browser Paths).

How do I use Chrome Canary?

Chrome Canary is fully supported. The script auto-detects it at these locations:

If auto-detection doesn’t find it, specify the path manually:

# macOS
./setup.sh --path "$HOME/Library/Application Support/Google/Chrome Canary"

# Linux (Canary uses the dev channel package "google-chrome-unstable")
./setup.sh --path "$HOME/.config/google-chrome-unstable"

# Windows (Canary is stored under "Chrome SxS")
.\setup.ps1 -Path "$env:LOCALAPPDATA\Google\Chrome SxS\User Data"

Note: On Linux, Chrome Canary and Chrome Dev share the same data directory (google-chrome-unstable) because they both use the google-chrome-unstable package. The setup script will configure the directory once for whichever is detected first.

How does Linux support work?

On Linux, Claude Code CLI provides the native messaging host — Claude Desktop is not available for Linux.

When you install Claude Code and run it, it creates a native host at ~/.claude/chrome/chrome-native-host and registers it for Google Chrome and Microsoft Edge. This tool extends that registration to additional Chromium browsers (Brave, Vivaldi, Opera, etc.).

Requirements:

• Claude Code CLI — npm install -g @anthropic-ai/claude-code
• Run claude at least once, then use /chrome to initialize the native host

See docs/linux-setup.md for detailed instructions.

How do I use a custom browser location?

Use the --path flag (Bash) or -Path parameter (PowerShell) to point the script at your browser’s data directory:

# macOS/Linux
./setup.sh --path "/absolute/path/to/browser/data-directory"

# Windows
.\setup.ps1 -Path "C:\path\to\browser\User Data"

The path must be:

• Absolute (no relative paths like ./browser or ../data)
• An existing directory that is readable
• A valid Chromium data directory (the script verifies this)

To find the correct path, open your browser and navigate to chrome://version — the Profile Path shows where data is stored. Use the parent directory of the profile folder.

Uninstall

macOS / Linux:

./setup.sh --uninstall

Linux (quick uninstall):

./uninstall-linux.sh

Windows:

.\setup.ps1 -Uninstall

Running Tests

# Bash tests
./tests/test_setup.sh

# PowerShell tests
.\tests\test_setup.ps1

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Areas where help is needed:

• Homebrew formula
• Chocolatey package
• AUR package for Arch Linux
• Additional browser support

Related Resources

• Claude Desktop - Official Claude desktop app (macOS/Windows)
• Claude Code - CLI tool for agentic coding (all platforms)
• Chrome Native Messaging - Chrome documentation

Related GitHub Issues

• #34364 - Bridge feature flag blocks non-Chrome browsers (our technical analysis)
• #18075 - Add CLAUDE_CODE_CHROME_PATH env var
• #14536 - Browser selection option
• #14370 - Detect extension in Chromium browsers

License

MIT License - See LICENSE for details.

Disclaimer

This is an unofficial workaround. The official Claude in Chrome extension is designed for Google Chrome only. Anthropic may change the native messaging implementation at any time. Use at your own risk.

Report Bug · Request Feature