Hermes Browser Extension

Browser-native side panel for Hermes Agent — connect active web context to your local or remote Hermes runtime.

Created by Jon Komet (@abundantbeing). Community extension for Hermes Agent by Nous Research.

Public alpha · Load unpacked · Local/remote Hermes API · Full Hermes runtime tools

Not on the Chrome Web Store yet.

What it is

Hermes Browser Extension is not a browser chatbot. It is a Chrome/Edge/Chromium side panel for the real Hermes Agent runtime. It talks to your Hermes Gateway/API server — local by default, remote when you configure a reachable URL — so it can use the models, tools, skills, sessions, memory, and MCP servers already configured in Hermes.

This repo is specifically for the Hermes Browser Extension: the Chrome/Edge/Chromium side-panel integration for Hermes Agent.

Visual tour

Side panel	Theme settings	Local agents
Browser behavior	Page-only context	Hermes compatibility

Highlights

• Chrome/Edge/Chromium MV3 side panel powered by the Side Panel API.
• Connects to a configurable local or remote Hermes API server. Default: http://127.0.0.1:8642.
• Supports dashboard WebSocket mode when you have a signed-in remote Hermes dashboard tab and no API key.
• Auto-syncs connected Hermes providers/models, profiles, skills, sessions, and capabilities.
• Keeps runtime plugins available in the same Hermes session. For example, a connected social or messaging plugin can add account, post, and trend context while the extension supplies browser-page context.
• Shows a Hermes compatibility panel so older gateways degrade into explicit fallback/manual modes instead of broken route errors.
• Adds Copy Diagnostics for v0.1.9 support reports: browser family, version/build, gateway origin, capability flags, context mode, and last visible error with tokens/page content stripped.
• Sends active tab/browser context into a persisted Hermes session, or switches to Chat only when you do not want browser context attached.
• Adds a composer-header context menu for Chat only, following the active tab, pinning a specific tab, and choosing which open tabs appear in the prompt.
• Opens as a tab-attached side panel by default, with a setting to keep the panel global across tabs.
• Opens with a keyboard shortcut (Alt+H by default, customizable at chrome://extensions/shortcuts).
• Keeps pinned-tab conversations isolated with per-tab local history and Hermes session bindings.
• Adds quick commands for common browser-context work, including /summarize, /explain, /rewrite, /tabs, and /action-items.
• Adds a collapsible “What Hermes saw” receipt after each sent turn for transparent context/debugging.
• Shows a live Tool Activity Strip while Hermes streams, so tool calls appear as structured runtime activity instead of raw [tool] markdown appended into answers.
• Classifies upstream Hermes runtime/tool exceptions as connected-with-warning diagnostics when the gateway is reachable, including the known Python NoneType/int() traceback class.
• Captures active tab title/URL, open tabs, selected text, readable page text, metadata, headings, forms, links, and buttons where available.
• Supports voice dictation through Hermes audio transcription when available, with Browser speech fallback when the connected runtime does not expose STT.
• Wraps webpage text as untrusted context before sending it to Hermes.
• Streams Hermes responses and falls back to non-streaming chat when needed.
• Includes Desktop-style appearance settings: Light/Dark/System mode plus Nous, Midnight, Ember, Mono, Cyberpunk, and Slate themes.
• Includes a localhost agent picker for switching between trusted local Hermes API gateway ports.
• No debugger, nativeMessaging, click/type/form-submit, cookies, history, bookmarks, downloads, or browser-control permissions in v0.1.

Requirements

• Hermes Agent installed and working.
• Hermes Gateway/API server enabled locally or on a reachable remote machine.
• Node.js 20+.
• Chrome, Edge, Brave, Comet, or another Chromium browser with Side Panel API support (Chrome 114+ baseline).

v0.1.9 compatibility matrix

Surface	Supported in v0.1.9	Fallback / note
Chrome / Edge / Chromium 114+ side panel	Yes	Primary public support target.
Brave / Comet / Chromium forks	Best-effort	Must expose the Chromium Side Panel API and extension clipboard permissions for Copy Diagnostics.
Firefox / Safari	Preview only	Diagnostics now report browser family, but cross-browser support is not shipped yet.
Local Hermes API server	Yes	Default path: http://127.0.0.1:8642.
Remote API server	Yes, explicit URL/token only	Use trusted LAN/Tailscale/VPN or HTTPS reverse proxy; do not expose Hermes naked to the internet.
Remote dashboard WebSocket	Best-effort	Chat/session/model path only; REST-only profile/skills/image-upload surfaces remain unavailable.
Browser Context Protocol	Yes	Extension emits hermes.browser.context.v1 payloads and keeps prompt-embedded fallback.
Companion plugin	Private prototype only	Optional fail-soft skeleton in companion-plugin/; not required for public v0.1.9.
Browser control / Runs UI / debugger / nativeMessaging	No	Deferred until supportability, action policy, approvals, and logs exist.

Quick start

1. Clone and build

git clone https://github.com/abundantbeing/hermes-browser-extension.git
cd hermes-browser-extension
npm install
npm run build

The loadable extension is generated at:

dist/

2. Load unpacked in Chrome/Edge

1. Open chrome://extensions or edge://extensions.
2. Enable Developer mode.
3. Click Load unpacked.
4. Select this repo's dist/ folder — not the repo root and not extension/.
5. Pin/click the Hermes extension icon to open the side panel.

After code updates, run npm run build again and click Reload on the Hermes Browser Extension card in the browser extensions page.

Connect to Hermes

Local API server

Local-only is the safest default. Put this in ~/.hermes/.env on the machine running Hermes:

API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642
API_SERVER_KEY=<your-api-server-key>
API_SERVER_CORS_ORIGINS=chrome-extension://<your-extension-id>

Start or restart the gateway:

hermes gateway run

Verify the API server:

HERMES_GATEWAY_URL=http://127.0.0.1:8642
HERMES_API_TOKEN='<your-api-server-key-or-browser-token>'
curl "$HERMES_GATEWAY_URL/health"
curl -H "Authorization: Bearer $HERMES_API_TOKEN" "$HERMES_GATEWAY_URL/v1/models"

Then in the extension side panel:

1. Click Connect to Hermes and approve locally if your Hermes Desktop/gateway supports the approval flow.
2. If approval is not available yet, click Manual setup.
3. Choose Local gateway.
4. Use Gateway URL http://127.0.0.1:8642.
5. Paste your scoped browser token or API_SERVER_KEY.
6. Click Test connection, then Save settings.
7. Open a normal https:// page and ask: Summarize this page in one sentence.

Remote API server

For a remote Hermes machine, bind the API server to a reachable trusted interface and keep CORS narrow:

API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642
API_SERVER_KEY=<your-api-server-key>
API_SERVER_CORS_ORIGINS=chrome-extension://<your-extension-id>

Use a private same-LAN/Tailscale/VPN host with HTTP, or put the API server behind a trusted HTTPS reverse proxy for public/proxied access. Do not expose the Hermes API server naked to the public internet. The Hermes API server can access the real Hermes runtime and tools.

Examples:

http://192.168.1.50:8642
http://hermes-desktop.local:8642
https://hermes.example.com

In the extension side panel:

1. Choose Remote gateway.
2. Paste the remote API URL, including http:// or https://.
3. Paste the API key/browser token.
4. Click Test connection.

With a key present, Remote means Remote API server and does not force HTTPS. With the key blank, Remote means Remote dashboard WebSocket and requires an https:// dashboard URL.

Remote dashboard mode, no API server

If you run Hermes elsewhere and only expose the OAuth-gated dashboard, select Remote, enter the dashboard's https:// URL, and leave the API key blank. With no key, the extension connects over the dashboard's /api/ws socket instead of the REST API server.

Auth uses a single-use WebSocket ticket minted from a signed-in dashboard tab:

• Open the dashboard URL in a normal browser tab and sign in, and keep that tab around.
• The extension mints the ticket first-party from that tab, then opens the socket.
• Test connection opens the socket and loads models, which confirms the whole path.

Limitations in this mode: image attachments are inline-only, and the skills/profiles lists are unavailable because those are REST-only and the dashboard's REST surface is not reachable cross-origin.

What syncs after connection

After connection, the side panel loads from the connected Hermes gateway:

• /v1/models — all providers/models Hermes can enumerate, including provider-qualified IDs.
• /api/sessions — recent Hermes sessions grouped by source.
• /v1/skills — slash-command skill suggestions in the composer.
• /v1/profiles — profile picker when the gateway exposes profile metadata.
• /v1/capabilities — feature flags such as audio transcription and Browser upload support.

The DOM/context chip should show a non-zero page-context count on normal readable pages. Browser internal pages such as chrome://extensions are intentionally restricted.

Install with Hermes / Computer Use

You can ask Hermes to help install it:

Install Hermes Browser Extension from https://github.com/abundantbeing/hermes-browser-extension. Clone it, run npm install, run npm run build, then use computer use to open chrome://extensions, enable Developer mode, load the dist folder unpacked, and help me connect it to my local or remote Hermes Gateway API server. Do not reveal, print, screenshot, or commit my API key.

Security model

Hermes Browser Extension is intentionally conservative in v0.1:

• Local API server by default; remote API server support requires an explicit URL, token, and CORS allowlist.
• Strong bearer/API key required for API access.
• Page content is wrapped as untrusted context before it reaches Hermes.
• Read-only browser context capture: no click, type, form-submit, checkout, download, or browser-control behavior.
• No debugger, nativeMessaging, cookies, history, downloads, or bookmarks permissions.
• Restricted pages include browser internals, extension pages, and obvious banking/crypto/password/payment/health/government-tax categories.

See SECURITY.md, PERMISSIONS.md, DATA-FLOW.md, and PRIVACY.md for details.

Troubleshooting

I loaded the extension but nothing works

Make sure you loaded dist/, not the repo root. The selected folder must contain manifest.json directly.

Chrome still shows an older version after updating

The browser is still using an old unpacked folder or an unpacked extension card that was not reloaded. For v0.1.9, the source manifest, built dist/ manifest, and release archive should all contain manifest.json version 0.1.9.

Fix:

1. Extract/download the v0.1.9 release or run npm run build locally.
2. Open chrome://extensions or edge://extensions.
3. On the Hermes Browser Extension card, click Reload.
4. If it still shows an older version, click Remove, then Load unpacked again and select the fresh v0.1.9 dist/ folder.
5. Click service worker / Inspect views only for debugging; it is not the version source.

Filing a support issue

Open Settings → Support diagnostics → Copy Diagnostics and paste the report into the GitHub issue or support thread.

The copied block includes version/build, browser family, gateway origin, connection state, runtime capability flags, selected model/provider, context mode, extractor mode, and last visible error. It intentionally excludes API keys, bearer tokens, cookies, page text, selected text, tab titles, and full tab URLs.

The side panel says it cannot connect

Check that Hermes Gateway/API server is running and reachable from the browser:

curl http://127.0.0.1:8642/health
# or, for remote mode:
curl http://<trusted-remote-host>:8642/health

If /v1/models fails, check `API_SERVER_KEY