Context-Aware Overlays

The signature PolyKybd feature: every key’s OLED shows an image (“overlay”) that matches whatever app you’re currently in. Switch from your browser to your editor and all 72 keycaps re-label themselves to that app’s shortcuts, with no action from you.

Overlays are driven by PolyKybdHost — the keyboard on its own shows the static legends baked into the firmware; the host is what makes them dynamic.

How it works

1. PolyKybdHost watches which window is focused on your computer.
2. When the active app changes, it looks up the overlay set for that app and pushes the keycap images to the keyboard over USB HID (compressed, so a full re-label is quick).
3. The master half decompresses the images into its display memory and relays them to the slave half over the split link, so both hands show the same thing.

Tip

Frequently-used apps are cached (the MRU — most-recently-used — cache), so returning to a recent app replays from cache instead of re-sending every image. The cache lives in PolyKybdHost and is rebuilt when the keyboard reconnects.

Modifier variants

An overlay isn’t a single image per key — each key stores 16 variants, one for every combination of Ctrl, Shift, Alt and GUI (Command on macOS, Win elsewhere). Hold a modifier and the keycaps update to show what each key does with that modifier down, so a shortcut layer is visible before you commit to it.

Tip

GUI combinations work now. Older releases showed the GUI key on its own, but folded every GUI+… chord onto it — so holding Cmd+Shift drew the plain Cmd icons rather than the right ones. That mattered most on macOS, where Cmd+Shift chords are everywhere. All sixteen combinations are addressable now, so an overlay can cover them.

What you need

• PolyKybdHost running on the machine you’re typing on (or relayed from another machine — see Multi-Machine Setup).
• An overlay set for the app. PolyKybdHost ships overlays for the apps listed below, and adding one is a plain image plus a one-line mapping entry — Create App Overlays walks through it.

Which apps are covered

These ship with PolyKybdHost and work as soon as it is running — nothing to install or configure.

	Apps
Browsers	Chrome, Chromium, Edge, Brave, Vivaldi, Opera, Arc
Web apps (by URL)	GitHub, GitLab, Jira, Confluence, Bitbucket, Google Docs, Miro, Notion, Outlook on the web
Office & documents	Word, Excel, PowerPoint, Outlook, LibreOffice Writer / Calc / Impress
Creative	Photoshop, Illustrator, After Effects, Premiere Pro, DaVinci Resolve, GIMP, Krita, Inkscape, Figma
Development	VS Code, Visual Studio, JetBrains IDEs (IntelliJ, PyCharm, CLion), Sublime Text, Notepad++, KiCad PCB Editor
Notes	Obsidian, Notion
Communication	Slack, Discord, Teams, Zoom
System (Windows)	Explorer, Task Manager, Notepad, Calculator, Paint, Paint.NET, WordPad, Sticky Notes, Photos, Snipping Tool, Sound Recorder, the lock screen
Terminals & transfer	PuTTY, WinSCP

A few entries are narrower than the app name suggests: KiCad covers the PCB Editor window specifically, and Notion appears twice because the desktop app and the web version are matched separately. Sound Recorder also answers to its Windows 10 name, Voice Recorder — same app, same keycaps.

Tip

Sublime Text ships a macOS-specific set alongside the default one — see Same app, different platform below.

Note

This is what ships today; the authoritative list is overlay-mapping.poly.yaml in PolyKybdHost. An app that isn’t here simply keeps the keyboard’s static legends — nothing breaks — and adding it yourself is a template image plus one mapping entry.

Same app, different platform

Which shortcuts an app uses depends on the platform it runs on: Sublime Text binds Cmd+P on macOS and Ctrl+P on Windows and Linux. A single set of artwork therefore can’t be right everywhere, so where an app has per-OS overlays the host picks the one matching your OS — Cmd artwork on macOS, Ctrl artwork elsewhere — with nothing to configure.

Tip

This follows the machine the app runs on, not the one your keyboard is plugged into. If you drive the keyboard from a Mac over a multi-machine setup, you still get the Mac artwork.

Tip

Browsers are a special case: many web apps share one browser process, so matching on the app name alone isn’t enough. Website-Aware Overlays match the overlay to the focused tab’s URL instead, so Jira, GitHub and Miro each get their own layer.

Note

Want the technical version — the exact HID commands, the compression path, and how both halves stay in sync? See System Model & Data Flow and the HID Protocol Reference.