Troubleshoot Claude Browser Extension Connectivity

This troubleshooting guide covers connectivity failures between a macOS Chrome extension and browser automation tools. It focuses on native messaging host configuration, bridge socket locations, competing desktop and command-line integrations, startup order, multiple browser profiles, and stale wrapper paths. It includes diagnostic commands for inspecting running host processes, sockets, open files, active configuration files, and the temporary directory.

Use the guide when an extension reports that the browser bridge is disconnected, automation is intermittent or timing out, or a native host is running but tool calls still fail. The procedures target macOS paths and utilities; they do not address Linux, Windows, general browser automation problems, network connectivity, or extension installation. It also distinguishes browser-related issues from unrelated desktop-app issues.

Inputs include the operating system, which desktop or command-line runtime is being used, whether Chrome and its extension are active, native host process details, socket location, active messaging configuration, and TMPDIR. The output is a diagnosis of whether Chrome launched the expected host and whether the bridge socket is available in the format the client expects. The guide describes a conflict where two installed integrations register distinct native hosts and expect different socket layouts. Selecting one runtime, ensuring its corresponding configuration is active, and starting Chrome and the client in the expected order can resolve that conflict.

A command used to locate the macOS temporary directory is:

getconf DARWIN_USER_TEMP_DIR

The diagnostic checklist compares the running host process with the socket path, checks open Unix sockets, lists active native messaging configurations, and inspects the custom wrapper and temporary directory. It notes that a browser bridge connection is established at client startup, so a bridge that was not ready then may require a client restart after Chrome and the extension are available.

Relevant components include Google Chrome, native messaging host configuration files, macOS temporary directories, Unix sockets, shell diagnostics, and a small toggle script for switching between two related runtime configurations. Limit the extension to one Chrome profile and avoid simultaneous sessions that contend for a socket. A wrapper should resolve the current executable dynamically instead of pinning an old version.

Some procedures in the source rename configuration files, stop host processes, remove sockets, and restart Chrome. Treat these as system-changing steps: first confirm which runtime and configuration are intended, inspect the exact target paths, and preserve a recovery copy before changing configuration. The guide's instructions are specific to its stated environment and should not be applied to unrelated browser setups.

macOS developers and support engineers diagnosing a native browser bridge can use the guide to identify mismatched host configuration, startup timing, profile duplication, and stale wrappers.