Website-Aware Overlays

Context-aware overlays normally pick a shortcut layer from the app you’re in. But a browser is a special case: Gmail, Jira, Figma and every other web app all run inside the same browser process, and their window titles are inconsistent — so the app name “chrome” isn’t enough to tell them apart.

Website detection fixes that: PolyKybdHost can see the URL of your focused browser tab and match an overlay to the website, so switching from Jira to Outlook in the same browser re-labels your keycaps just like switching between two native apps.

Note

This is entirely optional and off nothing else — with it disabled (or no URL available), browser overlays simply fall back to matching on the window title, exactly as before.

How the URL reaches the host

PolyKybdHost gets the active tab’s URL from one of two sources:

Platform	Source	Install needed
Windows / Linux	The browser extension (below)	Yes — install the extension
macOS (Chrome, Edge, Brave, Vivaldi, Opera, Arc, Safari)	Built-in AppleScript query	No — works out of the box
Firefox on macOS	The browser extension	Yes — AppleScript can’t read Firefox

The extension sends only the tab’s URL, its title, and whether the window is focused — to http://127.0.0.1 (your own machine) and nowhere else. No page content is ever read. See the extension privacy policy for the full details.

Tip

On macOS the first URL read triggers a one-time “PolyHost wants to control <Browser>” system prompt — allow it. Firefox on macOS has no AppleScript URL support, so Firefox users still need the extension.

Installing the browser extension

The extension works on all Chromium browsers (Chrome, Edge, Brave, Vivaldi, Opera, Arc) and Firefox. Once it’s published you’ll install it from the Chrome Web Store or Firefox Add-ons in one click, with automatic updates. To load it manually in the meantime:

• Chromium: chrome://extensions → enable Developer mode → Load unpacked → pick the dist/chromium/ folder from a build.sh run.
• Firefox: about:debugging#/runtime/this-firefox → Load Temporary Add-on → pick dist/firefox/manifest.json.

Then open the extension’s Options, confirm the Host port matches PolyKybdHost’s browser_report_port (default 50164), and click Test connection — it should read Connected to PolyKybdHost ✓.

Note

For managed fleets, IT can force-install the extension by policy instead of a per-user install (Chromium ExtensionInstallForcelist, Firefox policies.json with the add-on id website-reporter@polykybd).

Host settings

Website detection is controlled by a few settings in PolyKybdHost (Settings dialog, or polyctl settings):

Setting	Default	What it does
browser_url_detection	on	Master switch for the whole feature. Off → browser overlays match on title only.
browser_report_local_enabled	on	Runs the loopback receiver the extension posts to. Bound to 127.0.0.1 only.
browser_report_port	50164	Port the receiver listens on — must match the extension’s Host port.
browser_report_token	(empty)	Optional shared secret. When set, a report must present the same token (set it in the extension Options too) — extra defence against other local apps.

Mapping overlays to websites

In your overlay mapping, a browser entry can carry a urls-contains block: each key is a substring matched against the focused tab’s URL, and the first match wins. URL matches take priority over titles-contains, and both are kept so title matching still works whenever no URL is available.

chrome,google-chrome,chromium,brave,msedge,microsoft-edge,vivaldi,opera,arc:
  overlay: [chrome_template.mods.png, chrome_template.combo.mods.png]
  urls-contains:
    atlassian.net:   { overlay: jira_template.mods.png }
    outlook.office.com: { overlay: web_outlook_template.mods.png }
    miro.com:        { overlay: miro_template.mods.png }
  titles-contains:
    Jira:   { overlay: jira_template.mods.png }
    Outlook:{ overlay: web_outlook_template.mods.png }

Tip

Because a URL identifies a web app far more reliably than its title, an SPA route change (e.g. navigating within Jira) can swap overlays even when the window title doesn’t change.

Across two machines

Website detection also works for a computer you are forwarding from — see Multi-Machine Setup. Install the browser extension on the remote machine (it always reports to 127.0.0.1 on its own machine, so nothing about it changes) and run the forwarder with --report-rpc. The focused tab’s URL then travels with the window report, and your urls-contains entries match forwarded browsers exactly as local ones.

Caution

The URL only travels over the authenticated window-report path (--report-rpc). The legacy plaintext relay on port 50162 does not carry it — a forwarded browser falls back to title matching there. This is deliberate: that relay’s message format puts the window title in the middle of a ;-separated line, so adding another field would make a title containing a semicolon even more fragile than it already is.

See also

• Context-Aware Overlays — the general how-it-works.
• Multi-Machine Setup — relaying the focused window (and its URL) from another computer.
• Browser Extension Privacy Policy.