Claude Chrome Bridge

A network bridge that enables Claude Code running on a remote Linux machine to control Google Chrome on a Windows machine through the Claude Chrome extension.

Why This Exists

Claude Code uses Chrome's Native Messaging API to communicate with the Claude Chrome extension. Native Messaging only works locally via stdin/stdout pipes. This bridge tunnels that communication over TCP, allowing remote browser control.

Use Cases:

• Run Claude Code on a powerful Linux server while browsing on your Windows desktop
• Headless Linux environments that need browser automation on a separate Windows machine
• Development setups where Claude Code runs in WSL or a VM

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              LINUX MACHINE                                  │
│                                                                             │
│  ┌─────────────┐      ┌──────────────────────────────────────────┐         │
│  │ Claude Code │ ───► │ Unix Socket                              │         │
│  │    CLI      │      │ /tmp/claude-mcp-browser-bridge-{user}    │         │
│  └─────────────┘      └──────────────────────────────────────────┘         │
│                                        │                                    │
│                                        ▼                                    │
│                        ┌───────────────────────────────┐                   │
│                        │ socat                         │                   │
│                        │ UNIX-LISTEN → TCP forward     │                   │
│                        └───────────────────────────────┘                   │
│                                        │                                    │
└────────────────────────────────────────┼────────────────────────────────────┘
                                         │ TCP:9222
                                         ▼
┌────────────────────────────────────────┼────────────────────────────────────┐
│                              WINDOWS MACHINE                                │
│                                        │                                    │
│                        ┌───────────────────────────────┐                   │
│                        │ windows-bridge.js             │                   │
│                        │ TCP:9222 → Named Pipe         │                   │
│                        └───────────────────────────────┘                   │
│                                        │                                    │
│                                        ▼                                    │
│                        ┌───────────────────────────────┐                   │
│                        │ Claude Chrome Extension       │                   │
│                        │ (Native Messaging Host)       │                   │
│                        └───────────────────────────────┘                   │
│                                        │                                    │
│                                        ▼                                    │
│                        ┌───────────────────────────────┐                   │
│                        │ Google Chrome Browser         │                   │
│                        └───────────────────────────────┘                   │
└─────────────────────────────────────────────────────────────────────────────┘

Prerequisites

Windows Machine

• Windows 10/11
• Node.js v16 or later
• Google Chrome
• Claude Chrome extension (v1.0.36+)
• Network access from Linux machine (port 9222)

Linux Machine

• Claude Code CLI (v2.0.73+)
• socat utility
• Network access to Windows machine

Quick Start

1. Clone the Repository

git clone https://github.com/yourusername/claude-chrome-bridge.git
cd claude-chrome-bridge

2. Windows Setup

Copy windows-bridge.js to your Windows machine and run:

node windows-bridge.js

You should see:

[Bridge] ✓ TCP server listening on 0.0.0.0:9222

First-time setup: Before running the bridge, ensure the Claude Chrome extension's native messaging host is initialized:

1. Install the Claude Chrome extension
2. Run Claude Code locally on Windows once (claude --chrome)
3. This registers the native messaging host with Chrome

3. Linux Setup

Install socat if not already installed:

# Debian/Ubuntu
sudo apt install socat

# RHEL/CentOS/Fedora
sudo dnf install socat

# Arch Linux
sudo pacman -S socat

Start the socket forwarder:

# Replace WINDOWS_IP with your Windows machine's IP address
WINDOWS_IP="192.168.1.100"

# Remove any existing socket
rm -f /tmp/claude-mcp-browser-bridge-$(whoami)

# Start the forwarder (runs in background)
socat UNIX-LISTEN:/tmp/claude-mcp-browser-bridge-$(whoami),fork,mode=600 \
      TCP:${WINDOWS_IP}:9222 &

echo "Bridge started!"

4. Test the Connection

# Verify socat is running
ps aux | grep socat

# Check socket exists
ls -la /tmp/claude-mcp-browser-bridge-*

# Test TCP connectivity to Windows
nc -zv ${WINDOWS_IP} 9222

5. Use Claude Code

claude --chrome

Or within Claude Code, use the /chrome command.

Detailed Setup

Windows Firewall Configuration

Allow incoming connections on port 9222:

netsh advfirewall firewall add rule name="Claude Chrome Bridge" ^
    dir=in action=allow protocol=TCP localport=9222

Or via Windows Defender Firewall UI:

1. Open "Windows Defender Firewall with Advanced Security"
2. Click "Inbound Rules" → "New Rule"
3. Select "Port" → "TCP" → "9222"
4. Allow the connection
5. Name it "Claude Chrome Bridge"

Running as a Windows Service

For persistent operation, run the bridge as a Windows service using node-windows or NSSM.

Using NSSM:

# Download NSSM from https://nssm.cc/
nssm install ClaudeBridge "C:\Program Files\nodejs\node.exe" "C:\path\to\windows-bridge.js"
nssm start ClaudeBridge

Linux Systemd Service

Create /etc/systemd/user/claude-chrome-bridge.service:

[Unit]
Description=Claude Chrome Bridge Forwarder
After=network.target

[Service]
Type=simple
Environment="WINDOWS_IP=192.168.1.100"
ExecStartPre=/bin/rm -f /tmp/claude-mcp-browser-bridge-%u
ExecStart=/usr/bin/socat UNIX-LISTEN:/tmp/claude-mcp-browser-bridge-%u,fork,mode=600 TCP:${WINDOWS_IP}:9222
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable claude-chrome-bridge
systemctl --user start claude-chrome-bridge

Security Considerations

Warning: The default configuration has no authentication. Only use on trusted networks.

Option 1: SSH Tunnel (Recommended for untrusted networks)

Instead of exposing port 9222 directly, tunnel through SSH:

On Linux:

# Create SSH tunnel to Windows (requires SSH server on Windows)
ssh -L 9222:localhost:9222 user@windows-machine -N &

# Point socat at localhost instead
socat UNIX-LISTEN:/tmp/claude-mcp-browser-bridge-$(whoami),fork,mode=600 \
      TCP:localhost:9222 &

Option 2: Bind to Specific Interface

Modify windows-bridge.js to only listen on a specific interface:

const TCP_HOST = '192.168.1.100';  // Instead of '0.0.0.0'

Option 3: VPN

Run both machines on a VPN (WireGuard, Tailscale, etc.) and only expose the bridge on the VPN interface.

Troubleshooting

"Pipe not available" on Windows

[Bridge] Pipe not available: connect ENOENT \\.\pipe\claude-mcp-browser-bridge-username

Solutions:

1. Ensure Chrome is running
2. Verify Claude extension is installed and enabled (check chrome://extensions)
3. Run Claude Code locally on Windows once to initialize the native host
4. Restart Chrome after installing the extension

Connection refused from Linux

# Test connectivity
nc -zv 192.168.1.100 9222

# If connection refused:
# 1. Check Windows bridge is running
# 2. Check Windows Firewall settings
# 3. Verify IP address is correct

Socket permission denied on Linux

# Check who owns the socket
ls -la /tmp/claude-mcp-browser-bridge-*

# Remove and recreate if owned by wrong user
rm /tmp/claude-mcp-browser-bridge-*
# Then restart socat

socat exits immediately

Check if port 9222 is reachable before starting socat:

nc -zv ${WINDOWS_IP} 9222 && \
socat UNIX-LISTEN:/tmp/claude-mcp-browser-bridge-$(whoami),fork,mode=600 \
      TCP:${WINDOWS_IP}:9222

Configuration

Environment Variables

Variable	Default	Description
TCP_PORT	9222	Port for TCP connections
TCP_HOST	0.0.0.0	Interface to bind on Windows
WINDOWS_IP	-	Windows machine IP (Linux side)

Customizing the Port

Windows (windows-bridge.js):

const TCP_PORT = 9333;  // Change to desired port

Linux:

socat UNIX-LISTEN:/tmp/claude-mcp-browser-bridge-$(whoami),fork,mode=600 \
      TCP:${WINDOWS_IP}:9333

Version Requirements

Component	Minimum Version
Claude Code CLI	2.0.73+
Claude Chrome Extension	1.0.36+
Node.js	16+
Chrome	Any recent version

Limitations

• Latency: Network round-trip adds delay compared to local execution
• Single session: One Claude Code session at a time per bridge instance
• Chrome only: Does not work with Chromium variants (Brave, Arc, etc.)
• Visible window: Requires a visible Chrome window on Windows (no headless mode)
• No authentication: Relies on network security

Helper Scripts

Linux: start-bridge.sh

#!/bin/bash
# Start Claude Chrome bridge forwarder

WINDOWS_IP="${WINDOWS_IP:-192.168.1.100}"
TCP_PORT="${TCP_PORT:-9222}"
SOCKET_PATH="/tmp/claude-mcp-browser-bridge-$(whoami)"

# Kill existing forwarder
pkill -f "socat.*claude-mcp-browser-bridge" 2>/dev/null
sleep 1

# Remove old socket
rm -f "${SOCKET_PATH}"

# Test connectivity first
if ! nc -z "${WINDOWS_IP}" "${TCP_PORT}" 2>/dev/null; then
    echo "Error: Cannot reach ${WINDOWS_IP}:${TCP_PORT}"
    echo "Ensure Windows bridge is running and firewall allows connections"
    exit 1
fi

# Start forwarder
socat UNIX-LISTEN:${SOCKET_PATH},fork,mode=600 TCP:${WINDOWS_IP}:${TCP_PORT} &
SOCAT_PID=$!

echo "Bridge started (PID: ${SOCAT_PID})"
echo "  Socket: ${SOCKET_PATH}"
echo "  Target: ${WINDOWS_IP}:${TCP_PORT}"

Windows: start-bridge.bat

@echo off
cd /d "%~dp0"
echo Starting Claude Chrome Bridge...
node windows-bridge.js
pause

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - See LICENSE for details.

Acknowledgments

• Built for use with Claude Code by Anthropic
• Uses the Claude Chrome extension's native messaging infrastructure