What the bridge does
The FocusDragon Mac app and the browser extension are two separate processes that don't share memory, so they talk through a small native-messaging bridge on your Mac. It doesn't open a network port (which would trigger security prompts and break in firewalled environments), and you don't have to configure any of it: it's automatic.
During an AI Focus block, the extension uses the bridge to tell the FocusDragon app which tabs you have open (each tab's address and title, never page text) whenever they change. When AI Focus closes a browser, the app uses that list to offer your tabs back after the cooldown, and the extension closes the distracting tab when the browser opens again. Private windows are recorded as empty windows.
When the bridge breaks
AI Focus judges every check from a screenshot, so a broken bridge never changes what the dragon decides. What it can affect is your tabs: the distracting tab may come back when the browser reopens, and your other tabs may not be offered back.
If the extension itself is off or missing during an AI Focus block, FocusDragon shows a notice naming the browser: focusdragon.app/docs/ai-focus-notices
Common causes of the bridge breaking:
- FocusDragon was updated and the browser extension wasn't, or the other way round: the formats they exchange 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; 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 stopped by Chrome's idle timer and didn't restart cleanly.
Checking the extensions are ready
Open AI Focus in the sidebar before you start a block. When the extension is set up in every browser you have, the checklist's Browser extensions row says "Ready in every browser you have." If it names a browser instead, press Set up.
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 starts, or the handshake fails and it gives up.