What the bridge does
The FocusDragon Mac app and the browser extension are technically two separate processes that don't share memory. They need to talk for the AI classifier to ground itself: the Mac app needs to ask the extension "what's the active tab's URL and a short excerpt of its visible text?", and the extension needs to answer.
Rather than open a network port (which would trigger security prompts and break in firewalled environments), FocusDragon uses a small native-messaging bridge between the Mac app and the browser extension. You don't have to configure any of this — it's automatic.
When the bridge breaks
If the bridge stops working, the AI classifier falls back to screenshot-only analysis. You might notice the classifier feels less accurate without anything obviously broken.
Common causes of the bridge breaking:
- FocusDragon was updated and the browser extension wasn't, or vice versa — the request/response schemas can drift between versions for a release or two.
- The browser was launched before FocusDragon. The extension's native host expects FocusDragon to already be running and creating the request file; if it isn't, the host gives up after a few retries.
- macOS sandboxing reset the Application Support directory permissions after an OS update.
- The extension's background service worker (Chrome) was killed by Chrome's idle timer and didn't restart cleanly.
Verifying the bridge is working (Safari)
The simplest verification is functional: start an AI-classified session, browse to a non-blocked site you'd expect the AI to classify as work-related (e.g. your team's wiki), then open Settings → Insights in FocusDragon and check that the recent classifier verdict for that tab includes the page title, not just "unknown tab". A populated title is proof the bridge delivered the text excerpt.
Reset path (when the bridge is stuck)
- 1. Quit the browser completely (⌘Q — closing windows is not enough).
- 2. Quit FocusDragon (menu bar icon → Quit FocusDragon).
- 3. Launch FocusDragon FIRST. Wait until the menu bar icon appears and you can open the main window.
- 4. Now launch the browser. The order matters — the extension's native host needs to find FocusDragon already running when it boots, or the handshake fails and it gives up.