chrome-troubleshooter

name	chrome-troubleshooter
description	Diagnose and fix Claude Chrome extension connectivity issues. Use when browser automation tools fail with "extension not connected" or similar errors.
execution_mode	direct
tools_required	["Bash","Read"]

Chrome Extension Troubleshooter

Diagnose Claude Code CLI + Chrome extension connectivity issues.

When to Use

• mcp__claude-in-chrome__* tools fail
• "Browser extension is not connected" error
• Extension shows "Enabled" but tools timeout

Quick Diagnosis (Run These)

# 1. Can native host execute?
~/.claude/chrome/chrome-native-host --version 2>&1

# 2. Is socket created?
ls -la /var/folders/**/claude-mcp-browser-bridge* 2>/dev/null

# 3. Is process running?
pgrep -fl "chrome-native-host"

# 4. What does manifest point to?
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json | jq -r .path

# 5. Quarantine check
xattr ~/.claude/chrome/chrome-native-host

Failure Mode Decision Tree

Tools fail
    │
    ├── Native host --version fails?
    │   └── Gatekeeper Blockade → Fix: Remove quarantine
    │
    ├── Socket exists but no process?
    │   └── Zombie Bridge → Fix: Delete socket, restart Chrome
    │
    ├── Manifest path wrong?
    │   └── Path Rot → Fix: Edit manifest (see docs)
    │
    └── Everything looks OK?
        └── Service Worker stuck → Fix: Full Chrome restart (Cmd+Q)

Fixes

Fix 1: Remove Quarantine (Gatekeeper)

xattr -d com.apple.quarantine ~/.claude/chrome/chrome-native-host
chmod +x ~/.claude/chrome/chrome-native-host

Fix 2: Delete Orphan Socket

rm /var/folders/**/claude-mcp-browser-bridge* 2>/dev/null

Fix 3: Full Chrome Restart

osascript -e 'tell application "Google Chrome" to quit'
sleep 3
open -a "Google Chrome"

Fix 4: Edit Manifest Path (Desktop → CLI)

Chrome extension requests com.anthropic.claude_browser_extension which points to Desktop by default.

# Backup
cp ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.bak

# Edit manifest
nano ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json

Change path from:

"path": "/Applications/Claude.app/Contents/Helpers/chrome-native-host"

To:

"path": "/Users/YOUR_USERNAME/.claude/chrome/chrome-native-host"

Then restart Chrome. To revert, restore the .bak file.

Architecture

Claude Code CLI → MCP Server → chrome-native-host → Chrome Native Messaging → Extension
                                    ↓
                         Unix socket in /var/folders/

Key points:

• Extension requests native host by name: com.anthropic.claude_browser_extension
• Manifest at: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/
• Socket at: /var/folders/.../claude-mcp-browser-bridge-{username}

Common Gotchas

1. Desktop vs CLI conflict: Only one can own the native host at a time
2. Multiple Chromium browsers: Each has separate NativeMessagingHosts directory:
   • Chrome: ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/
   • Arc: ~/Library/Application Support/Arc/User Data/NativeMessagingHosts/
   • Brave: ~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts/
   • Edge: ~/Library/Application Support/Microsoft Edge/NativeMessagingHosts/
3. After CLI update: Native host binary may change, verify it exists
4. Service worker caching: Sometimes needs full browser restart, not just reload