# Claude In Chrome Troubleshooting

> Diagnoses macOS Claude in Chrome MCP native-host conflicts between Claude.app (Cowork) and Claude Code CLI sockets. Use when mcp__claude-in-chrome__* tools fail, return Browser extension is not connected, or behave erratically after updates. Not for Linux or Windows hosts, general Chrome automation, Claude.app desktop bugs, network outages, or Chrome Web Store install issues.

- Skill: `gabrielmoreira/claude-in-chrome-troubleshooting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/claude-in-chrome-troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/claude-in-chrome-troubleshooting/raw
- Safety review: pending (external: skill-scanner PASS, skillspector FAIL)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/claude-in-chrome-troubleshooting

---


## When to Use

- `mcp__claude-in-chrome__*` tools fail with "Browser extension is not connected"
- Browser automation works erratically or times out
- After updating Claude Code or Claude.app
- When switching between Claude Code CLI and Claude.app (Cowork)
- Native host process is running but MCP tools still fail

**When NOT to use:**
- Linux or Windows users — this skill covers macOS-specific paths and tools (`~/Library/Application Support/`, `osascript`, `$TMPDIR`)
- General Chrome automation issues unrelated to the Claude extension
- Claude.app desktop issues (not browser-related)
- Network connectivity problems
- Chrome extension installation issues (use Chrome Web Store support)

## Prerequisites

- macOS host (this skill is macOS-only; paths and commands use `osascript`, `getconf DARWIN_USER_TEMP_DIR`, and `~/Library/Application Support/`)
- Google Chrome installed
- Claude in Chrome extension installed from the Chrome Web Store
- Claude Code CLI and/or Claude.app installed
- Shell access (bash/zsh)

## Procedure

### Step 1: Identify the Primary Conflict

Claude.app (Cowork) and Claude Code CLI each register a **competing native messaging host** in Chrome. They use incompatible socket formats and locations. Only one can be active at a time.

| Component | Native Host Binary | Socket Location |
|-----------|-------------------|-----------------|
| **Claude.app (Cowork)** | `/Applications/Claude.app/Contents/Helpers/chrome-native-host` | `/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock` |
| **Claude Code CLI** | `~/.local/share/claude/versions/<version> --chrome-native-host` | `$TMPDIR/claude-mcp-browser-bridge-$USER` (single file) |

Both register native messaging configs in Chrome:
- `com.anthropic.claude_browser_extension.json` → Claude.app helper
- `com.anthropic.claude_code_browser_extension.json` → Claude Code wrapper

If the wrong config is active, the wrong binary runs, creating sockets in a format/location the MCP client doesn't expect. Result: "Browser extension is not connected" even though everything appears to be running.

### Step 2: Run Quick Diagnosis

```bash
# 1. Which native host binary is running?
ps aux | grep chrome-native-host | grep -v grep
# Claude.app: /Applications/Claude.app/Contents/Helpers/chrome-native-host
# Claude Code: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 2. Where is the socket?
# For Claude Code (single file in TMPDIR):
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

# For Claude.app (directory with PID files):
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

# 3. What's the native host connected to?
lsof -U 2>&1 | grep claude-mcp-browser-bridge

# 4. Which configs are active?
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json
```

### Step 3: Disable the Conflicting Native Host

**If you use Claude Code CLI for browser automation (not Cowork):**

```bash
# Disable the Claude.app native messaging config
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled

# Ensure the Claude Code config exists and points to the wrapper
cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json
```

**If you use Cowork (Claude.app) for browser automation:**

```bash
# Disable the Claude Code native messaging config
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json \
   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json.disabled
```

**You cannot use both simultaneously.** Pick one and disable the other.

### Step 4: Toggle Script (Optional)

Add this to `~/.zshrc` or run directly:

```bash
chrome-mcp-toggle() {
    local CONFIG_DIR=~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
    local CLAUDE_APP="$CONFIG_DIR/com.anthropic.claude_browser_extension.json"
    local CLAUDE_CODE="$CONFIG_DIR/com.anthropic.claude_code_browser_extension.json"

    if [[ -f "$CLAUDE_APP" && ! -f "$CLAUDE_APP.disabled" ]]; then
        # Currently using Claude.app, switch to Claude Code
        mv "$CLAUDE_APP" "$CLAUDE_APP.disabled"
        [[ -f "$CLAUDE_CODE.disabled" ]] && mv "$CLAUDE_CODE.disabled" "$CLAUDE_CODE"
        echo "Switched to Claude Code CLI"
        echo "Restart Chrome and Claude Code to apply"
    elif [[ -f "$CLAUDE_CODE" && ! -f "$CLAUDE_CODE.disabled" ]]; then
        # Currently using Claude Code, switch to Claude.app
        mv "$CLAUDE_CODE" "$CLAUDE_CODE.disabled"
        [[ -f "$CLAUDE_APP.disabled" ]] && mv "$CLAUDE_APP.disabled" "$CLAUDE_APP"
        echo "Switched to Claude.app (Cowork)"
        echo "Restart Chrome to apply"
    else
        echo "Current state unclear. Check configs:"
        ls -la "$CONFIG_DIR"/com.anthropic*.json* 2>/dev/null
    fi
}
```

Usage: `chrome-mcp-toggle` then restart Chrome (and Claude Code if switching to CLI).

### Step 5: Full Reset Procedure (Claude Code CLI)

If quick fixes don't work, perform a full reset:

```bash
# 1. Ensure correct config is active
mv ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json \
   ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json.disabled 2>/dev/null

# 2. Update the wrapper to use latest Claude Code version
cat > ~/.claude/chrome/chrome-native-host << 'EOF'
#!/bin/bash
LATEST=$(ls -t ~/.local/share/claude/versions/ 2>/dev/null | head -1)
exec "$HOME/.local/share/claude/versions/$LATEST" --chrome-native-host
EOF
chmod +x ~/.claude/chrome/chrome-native-host

# 3. Kill existing native host and clean sockets
pkill -f chrome-native-host
rm -rf /tmp/claude-mcp-browser-bridge-$USER/
rm -f "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"

# 4. Restart Chrome
osascript -e 'quit app "Google Chrome"' && sleep 2 && open -a "Google Chrome"

# 5. Wait for Chrome, click Claude extension icon

# 6. Verify correct native host is running
ps aux | grep chrome-native-host | grep -v grep
# Should show: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 7. Verify socket exists
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"

# 8. Restart Claude Code
```

### Step 6: Diagnostic Deep Dive

If the above steps don't resolve the issue, run the full diagnostic:

```bash
echo "=== Native Host Binary ==="
ps aux | grep chrome-native-host | grep -v grep

echo -e "\n=== Socket (Claude Code location) ==="
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER" 2>&1

echo -e "\n=== Socket (Claude.app location) ==="
ls -la /tmp/claude-mcp-browser-bridge-$USER/ 2>&1

echo -e "\n=== Native Host Open Files ==="
pgrep -f chrome-native-host | xargs -I {} lsof -p {} 2>/dev/null | grep -E "(sock|claude-mcp)"

echo -e "\n=== Active Native Messaging Configs ==="
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json 2>/dev/null

echo -e "\n=== Custom Wrapper Contents ==="
cat ~/.claude/chrome/chrome-native-host 2>/dev/null || echo "No custom wrapper"

echo -e "\n=== TMPDIR ==="
echo "TMPDIR=$TMPDIR"
echo "Expected: $(getconf DARWIN_USER_TEMP_DIR)"
```

## Pitfalls

1. **MCP connects at startup only.** If the browser bridge wasn't ready when Claude Code started, the connection will fail for the entire session. The fix is: ensure Chrome + extension are running with correct config, THEN restart Claude Code. Do not skip the Claude Code restart.

2. **Multiple Chrome Profiles.** If the Claude extension is installed in multiple Chrome profiles, each spawns its own native host and socket, causing confusion. Fix: Only enable the Claude extension in ONE Chrome profile.

3. **Multiple Claude Code Sessions.** Running multiple Claude Code instances causes socket conflicts. Fix: Only run one Claude Code session at a time, or use `/mcp` to reconnect after closing other sessions.

4. **Hardcoded Version in Wrapper.** The wrapper at `~/.claude/chrome/chrome-native-host` may have a hardcoded version that becomes stale after updates.
   ```bash
   cat ~/.claude/chrome/chrome-native-host
   # Bad: exec "/Users/.../.local/share/claude/versions/2.0.76" --chrome-native-host
   # Good: Uses $(ls -t ...) to find latest
   ```
   Fix: Use the dynamic version wrapper shown in the Full Reset Procedure (Step 5).

5. **TMPDIR Not Set.** Claude Code expects `TMPDIR` to be set to find the socket.
   ```bash
   # Check
   echo $TMPDIR
   # Should show: /var/folders/XX/.../T/

   # Fix: Add to ~/.zshrc
   export TMPDIR="${TMPDIR:-$(getconf DARWIN_USER_TEMP_DIR)}"
   ```

6. **Cannot use both hosts simultaneously.** Claude.app (Cowork) and Claude Code CLI native hosts are mutually exclusive. You must disable one for the other to work.

## Verification

After applying fixes, verify the connection is working:

```bash
# 1. Verify correct native host is running (Claude Code CLI)
ps aux | grep chrome-native-host | grep -v grep
# Expected: ~/.local/share/claude/versions/X.X.X --chrome-native-host

# 2. Verify socket exists (Claude Code CLI)
ls -la "$(getconf DARWIN_USER_TEMP_DIR)/claude-mcp-browser-bridge-$USER"
# Expected: socket file exists and is not stale

# 3. Verify only one config is active
ls ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic*.json
# Expected: only one .json file (the other should be .json.disabled)

# 4. Verify TMPDIR is set
echo $TMPDIR
# Expected: /var/folders/XX/.../T/

# 5. Test MCP tool from Claude Code
# Call any mcp__claude-in-chrome__* tool — should return successfully
# instead of "Browser extension is not connected"
```

## File Reference

| File | Purpose |
|------|---------|
| `~/.claude/chrome/chrome-native-host` | Custom wrapper script for Claude Code |
| `/Applications/Claude.app/Contents/Helpers/chrome-native-host` | Claude.app (Cowork) native host |
| `~/.local/share/claude/versions/<version>` | Claude Code binary (run with `--chrome-native-host`) |
| `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_browser_extension.json` | Config for Claude.app native host |
| `~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.anthropic.claude_code_browser_extension.json` | Config for Claude Code native host |
| `$TMPDIR/claude-mcp-browser-bridge-$USER` | Socket file (Claude Code) |
| `/tmp/claude-mcp-browser-bridge-$USER/<PID>.sock` | Socket files (Claude.app) |

## Related Skills

- Any skill that uses `mcp__claude-in-chrome__*` tools for browser automation may trigger this troubleshooting skill when those tools fail.

---

*Original skill by [@jeffzwang](https://github.com/jeffzwang) from [@ExaAILabs](https://github.com/ExaAILabs). Enhanced and updated for current versions of Claude Desktop and Claude Code.*