# Hermes Browser Extension on Firefox

Firefox runs the same extension as Chromium, in its own sidebar, with fewer powers. This guide says what works, what is limited and what is unavailable on each surface, why, and what to do instead. Settings > About & Diagnostics shows the Firefox limits inside the extension (**Firefox limits**), so you can read them before you start a task.

Hermes Control is not Chromium-only. Firefox has a restricted Hermes Control: it can read the page, open addresses, scroll, take a screenshot you allow, and list, open, switch and close tabs. It cannot click, type or press keys, because that needs trusted input, which Firefox gives an extension no way to send. That is the one large gap; the tables below list the rest.

Written against Firefox 159.0.1 on Windows and the extension at v0.4.0.

## How to read the tables

| Status | Meaning |
| --- | --- |
| Supported | Works the way it does on Chromium, or as described. |
| Limited | Works with a stated restriction. |
| Experimental | Built, but not shown to work in Firefox yet. Expect to need the fallback. |
| Unavailable | Not there. The fallback column says what to do. |

**Decided by** says what sets the limit: the browser's own API (`Browser API`), a permission you can grant (`Permission`), your Hermes gateway (`Gateway`), the connection to it (`Transport`), something this extension does not offer, whether retired or not built yet (`Not offered by the extension`), or nothing but the extension's own code (`Extension code`).

A dagger (†) marks a Firefox cell that has not been run in Firefox: it is the same code that runs on Chromium, so the status is what the code supports, not something anyone has watched happen. A cell without a dagger was read from the manifest, the Firefox build profile, the code and its tests.

Beyond reading the code, these were run in a real browser while writing this guide (Chrome for Testing, and Firefox 159.0.1 with a temporary install of the Firefox build): which shortcuts each browser registers, that Firefox has no `debugger`, `offscreen`, `sidePanel` or browser speech recognition API, that every right-click menu context is accepted and nests under the Hermes entry, and that Hermes Assist's draft host appears next to a focused field on a page. Nothing here was run against a Hermes gateway on Firefox.

The tables below are generated from `extension/lib/browser-capability-matrix.mjs` (`npm run sync:capabilities`). A test fails if they drift from it, and other tests pin each row to the manifest, the Firefox build profile or the code that decides it.

## The matrix

<!-- capability-matrix:start (generated by npm run sync:capabilities) -->

### Side panel and Firefox sidebar

| Feature | Chromium | Firefox | Why on Firefox | Decided by | Instead |
| --- | --- | --- | --- | --- | --- |
| Hermes in the browser side | Supported | Supported | Firefox's own sidebar (declared as sidebar_action); the Chromium side panel API does not exist there. | Browser API | - |
| Side panel tied to one tab | Supported | Unavailable | Firefox keeps an add-on sidebar open on every tab of the window, and giving it a panel per tab reloads it and ends chats in progress. | Browser API | The sidebar stays open across tabs; the toolbar button closes it. |
| Chat, attachments and page context | Supported | Supported † | Same code as Chromium: your Hermes gateway and the extension content script. | Gateway | - |
| Wake word in the side panel | Supported | Limited | Firefox has no offscreen documents, so the local listener cannot run. Hermes's own wake engine runs only on a local gateway on this computer, not on remote or cloud connections. | Browser API | Connect to a local gateway to use Hermes wake, or start the chat from the panel. |
| Voice dictation in the composer | Supported | Limited | Firefox has no browser speech recognition, so dictation works only through Hermes's own transcription (a gateway with audio transcription, or the dashboard on this computer). | Browser API | Type instead, or turn on audio transcription on your Hermes gateway. |

### Hermes Assist (drafting in page fields)

| Feature | Chromium | Firefox | Why on Firefox | Decided by | Instead |
| --- | --- | --- | --- | --- | --- |
| Assist circle and drafts in page fields | Supported | Supported | The same content script, declared for Firefox too; its draft host appears next to a focused field. | Extension code | - |
| Writing a reviewed draft into the field | Supported | Supported † | Same code as Chromium: you review the draft first; editors that manage their own text get a preview and Copy. | Extension code | - |
| Assist drafts that open the side panel | Supported | Experimental † | Firefox lets an extension open its sidebar only from a user action. A click relayed from the page to the background worker has not been tested, and when Firefox refuses and no sidebar is open, Hermes stops the draft and asks you to open the sidebar or run in the background. | Browser API | Open the sidebar first (Ctrl+Shift+H or the toolbar button), then draft. Or choose Run in background. |
| Drafts that need no open panel | Supported | Supported † | Same code as Chromium: the background worker asks your gateway for the draft. | Gateway | - |

### Hermes Web (full tab)

| Feature | Chromium | Firefox | Why on Firefox | Decided by | Instead |
| --- | --- | --- | --- | --- | --- |
| Open Hermes Web from the panel | Supported | Supported † | Same code as Chromium: opens the Webapp your gateway serves, in a normal tab. | Gateway | - |
| Signed-in Hermes Web launch | Supported | Supported † | Same code as Chromium: one-use sign-in only on loopback with pairing routes (otherwise run hermes webapp once on this computer); a remote Web address uses account sign-in instead. | Gateway | - |
| The extension chat in a full tab | Unavailable | Unavailable | The full-page chat view was retired; the sidebar is the supported surface. | Not offered by the extension | Use Hermes Web for a full page. |

### Hermes Control (acting in tabs you attach)

| Feature | Chromium | Firefox | Why on Firefox | Decided by | Instead |
| --- | --- | --- | --- | --- | --- |
| Hermes Control: attach tabs, scope and approvals | Supported | Supported | Same attach, scope, approval and restricted-page rules as Chromium, on a smaller set of actions. | Gateway | - |
| Hermes Control: reading the page | Supported | Limited | Firefox has no accessibility tree for extensions: Hermes reads the top page text and its list of controls with a content script, and nothing inside frames. | Browser API | Ask Hermes to work from the page text; copy anything inside a frame into the chat. |
| Hermes Control: navigate, back and scroll | Supported | Limited | Firefox scroll calls move a fixed distance in the page and ignore the amount argument Chromium honors. | Browser API | Repeat scroll for larger moves, or ask the person to scroll manually. |
| Hermes Control: list, open, switch and close tabs | Supported | Supported | Tabs API; only tabs you attached and tabs Hermes opened. Switching and closing ask you first. | Browser API | - |
| Hermes Control: screenshots | Supported | Limited | Firefox allows a capture only with all-sites access, which is optional and asked for from a click. Only the whole visible tab can be captured, and it must be the tab the window shows. | Permission | Click Allow screenshots on Firefox in Settings, or have Hermes read the page text. |
| Hermes Control: clicks, typing and key presses | Supported | Unavailable | Firefox has no debugger API, so an extension cannot send trusted clicks, typing or key presses, and Hermes does not imitate them with page events. | Browser API | Hermes can read the page and open addresses; do the click or typing yourself, or use a Chromium browser for the task. |
| Hermes Control: controls inside frames | Limited | Unavailable | Frame control needs the debugger API, which Firefox does not have; the page text Hermes reads leaves out frames. | Browser API | Open the framed page in its own tab. |
| Hermes Control: tab groups | Supported | Unavailable | Firefox has the tabs.group call, but the Firefox adapter does not offer grouping yet. | Not offered by the extension | Hermes still opens and closes its own tabs; they are just not grouped. |
| Hermes Control: action batches | Supported | Unavailable | The Firefox adapter does not offer batches yet, and most steps in a batch (clicks, typing) are unavailable there anyway. | Not offered by the extension | Hermes runs the steps one at a time. |

### Context menus and shortcuts

| Feature | Chromium | Firefox | Why on Firefox | Decided by | Instead |
| --- | --- | --- | --- | --- | --- |
| Right-click menu | Supported | Supported | The same submenu, on the same kinds of target, through the contextMenus permission. | Browser API | - |
| Toolbar button | Supported | Supported | Opens the sidebar, and closes it again when it is already open. | Browser API | - |
| Open shortcut: Alt+H | Supported | Supported | Alt+H runs the toolbar button. Change it on about:addons under Manage Extension Shortcuts. | Browser API | - |
| Sidebar shortcut: Ctrl+Shift+H | Unavailable | Supported | Ctrl+Shift+H (Command+Shift+H on macOS) opens the sidebar. | Browser API | - |

### What is not fully supported on Chromium

| Feature | Chromium | Why | Instead |
| --- | --- | --- | --- |
| The extension chat in a full tab | Unavailable | The full-page chat view was retired; the side panel is the supported surface. | Use Hermes Web for a full page. |
| Hermes Control: controls inside frames | Limited | Controls in same-site frames of an attached page. Frames from other sites run in their own process and are not read or acted on. | Open the framed page in its own tab. |
| Sidebar shortcut: Ctrl+Shift+H | Unavailable | Chromium has no sidebar command, so the manifest entry registers nothing there. | Use Alt+H. |

<!-- capability-matrix:end -->

## Hermes Control on Firefox

Hermes Control is opt-in and works only in tabs you attach. On Firefox the same rules apply as on Chromium: tab scope, approval for risky actions, restricted pages and blocked sensitive fields. Nothing is relaxed to make up for a missing API.

What Hermes can do in an attached Firefox tab: read the page text and its list of controls (`tab_snapshot`), open an address (`tab_navigate`), go back (`tab_back`), scroll (`tab_scroll`), take a screenshot (`tab_screenshot`, after **Allow screenshots on Firefox**), and list, open, switch to and close tabs (`tab_list`, `tab_create`, `tab_activate`, `tab_close`).

What it cannot do: click, type, fill, select, press keys, hover, drag, scroll to an element, group tabs or run batches. Hermes does not imitate trusted input with page events, so those actions are not offered rather than faked. When a chat asks for one anyway, the answer names the actions this browser does offer, so Hermes can switch to one of them or ask you to do the step. Hermes Control itself also needs a Hermes with Hermes Control: built in on Hermes 0.22.5 and earlier, the extension's Hermes plugin on current Hermes (see [companion-plugin/README.md](../companion-plugin/README.md)).

## Hermes Web on Firefox

Hermes Web is the Webapp your own gateway serves, opened in a normal browser tab by the panel. The extension's own full-page chat view was retired in both browsers; the sidebar (Firefox) and the side panel (Chromium) are the supported chat surfaces.

## Shortcuts

Alt+H runs the toolbar button on both browsers. Ctrl+Shift+H (Command+Shift+H on macOS) opens the sidebar and exists only on Firefox: Chromium has no sidebar command, so it registers nothing there. Firefox lets you change either on `about:addons`, under the gear menu, **Manage Extension Shortcuts**.

## Not covered

Not audited in this guide, and so not in the tables: Bot Mode group rooms, Projects, theme marketplace downloads and page comments. They use no Chromium-only API that was found, but nobody has run them in the Firefox sidebar. File an issue with your Firefox version, Windows version and extension build from **Copy Diagnostics** if one fails.