Install the browser bridge

The historia-collect installer connects the unpacked browser extension to the local native-messaging host. It discovers or creates the executable path, writes the browser manifest, limits it to Historia’s stable extension identity, and verifies the resulting registration.

Install

Chrome

historia-collect install --browser chrome

Chromium

historia-collect install --browser chromium

Brave

historia-collect install --browser brave

Edge

historia-collect install --browser edge

Firefox 140+

historia-collect install --browser firefox

Configure several browsers in one operation:

historia-collect install \
  --browser chrome \
  --browser firefox

The JSON response includes the native-host manifest path, executable or launcher path, extension identity, unpacked extension directory, browser extensions page, and post-install checks.

Stable identities

Chromium-family browsers derive the same extension ID on every machine from the public key committed in extension/manifest.json:

idfjphfgkpmmgggnbomlalheckgdcefj

Firefox uses:

[email protected]

Each native-host manifest permits exactly one of these identities. Unrelated extensions cannot invoke the host through that registration.

Public identity, not a private signing key

The repository contains only the public Chromium manifest key needed to derive a stable unpacked-extension ID. It does not contain a private extension signing key.

Load the unpacked extension

1. Open the extensions page reported by the installer.

   Browser	Page
   Chrome / Chromium	chrome://extensions
   Brave	brave://extensions
   Microsoft Edge	edge://extensions
   Firefox	about:debugging#/runtime/this-firefox

2. Enable developer mode where required.

3. Choose Load unpacked and select the extension directory from the installer output. Firefox uses Load Temporary Add-on while the extension remains unpacked.

4. Review the collection disclosure. Firefox 140 or newer presents built-in consent for rendered page identity, chat messages, and visible website content transferred to the local native host.

5. Open the Historia Collect popup and choose Check connection.

A successful check crosses the native-messaging boundary and confirms that the extension identity, browser manifest, executable, and host protocol agree.

The Firefox transfer is local

Firefox’s declared categories are browsingActivity, personalCommunications, and websiteContent. In Historia Collect these categories describe data sent to ai.greenways.historia_collect on the same computer—not a Greenways cloud service. See Privacy and data handling.

Diagnose

historia-collect doctor --browser chrome

The diagnostic exits non-zero when any requested registration is invalid. It checks that:

• the manifest exists and parses;
• the host name is ai.greenways.historia_collect;
• the extension allowlist is exact;
• the referenced host exists and is executable;
• the Windows current-user registry entry exists where applicable;
• the unpacked extension directory is available.

Host resolution

The installer chooses the native host in this order:

1. --host-path <absolute-path>;
2. HISTORIA_COLLECT_HOST;
3. a compiled historia-collect-host beside the running executable;
4. dist/historia-collect-host inside the package;
5. on macOS and Linux, an owner-only launcher using the absolute Bun runtime and package-native entry path.

Windows requires a compiled historia-collect-host.exe or an explicit --host-path.

Registration locations

The installer uses standard user-scoped locations and does not require administrator privileges:

Platform	Registration
macOS	Browser NativeMessagingHosts directory beneath ~/Library/Application Support.
Linux	Browser directory beneath ~/.config; Firefox uses ~/.mozilla/native-messaging-hosts.
Windows	Manifest beneath %LOCALAPPDATA%\Historia and a browser-specific HKCU registry entry.

Remove the bridge

historia-collect uninstall \
  --browser chrome \
  --browser firefox

This removes the selected manifests and Windows registry entries. It does not delete the Git vault, SQLite index, imported conversations, or extension settings.

Packaging-system integration

Use an explicit host path when Homebrew, a system package, or another installer owns executable placement:

historia-collect install \
  --browser chrome \
  --host-path /opt/historia/bin/historia-collect-host

The lower-level generator remains available:

historia collect native-manifest \
  --browser chrome \
  --extension-id idfjphfgkpmmgggnbomlalheckgdcefj \
  --host-path /absolute/path/to/historia-collect-host \
  --output /tmp/ai.greenways.historia_collect.json