KeyPeek

KeyPeek provides real-time layout visualization and an integrated keymap editor for QMK, Vial, and ZMK keyboards, running in two ways:

• Desktop app: Designed for active daily use. A live on-screen overlay that mirrors base and momentary layers in real time (especially useful when learning complex layouts or using boards with missing legends), with the ability to tweak keys directly without interrupting your workflow.
• Web app: A zero-install browser editor (USB and bluetooth) focused on inspecting layouts and remapping keys, sending keycode and behavior updates to the device on the fly from any computer.

Get desktop app  |  Open web app

Setup

Using the desktop overlay requires a small firmware change because stock QMK, Vial, and ZMK firmware do not expose live layer-change events. The module adds this event stream over the device connection so the overlay stays in sync with your active layers in real time while typing.

Note

If you only plan to use KeyPeek for keymap editing, this firmware modification is not needed.

QMK and Vial

1. In your QMK userspace (or qmk_firmware) root, add the module repo:

   mkdir -p modules
   git submodule add https://github.com/srwi/qmk-modules.git modules/srwi
   git submodule update --init --recursive

2. In your keymap folder, add srwi/keypeek_layer_notify to keymap.json:

   {
     "modules": [
       "srwi/keypeek_layer_notify"
     ]
   }

3. In the same keymap folder, enable RAW HID and VIA in rules.mk:

   RAW_ENABLE = yes
   VIA_ENABLE = yes

4. Build and flash your firmware:

   qmk compile -kb <your_keyboard> -km <your_keymap>

5. QMK only: Export layout information to keyboard_info.json:

   qmk info -kb <your_keyboard> -m -f json > keyboard_info.json

   This last step is only required for QMK keyboards, because VIA does not provide physical layout data directly over the connection. Vial keyboards do not require this step, as the layout data is transmitted when connecting the keyboard to KeyPeek.

ZMK

1. Add the KeyPeek module to your zmk-config/config/west.yml:

   manifest:
     remotes:
       - name: zmkfirmware
         url-base: https://github.com/zmkfirmware
       - name: zzeneg # <-- required for Raw HID module
         url-base: https://github.com/zzeneg
       - name: srwi # <-- required for KeyPeek module
         url-base: https://github.com/srwi
     projects:
       - name: zmk
         remote: zmkfirmware
         revision: main
         import: app/west.yml
       - name: zmk-raw-hid # <-- Raw HID module
         remote: zzeneg
         revision: main
       - name: zmk-keypeek-layer-notifier # <-- KeyPeek module
         remote: srwi
         revision: master

2. Add the raw_hid_adapter as an additional shield to your build, e.g. in build.yaml:

   include:
     - board: nice_nano_v2
       shield: <existing shields> raw_hid_adapter # <-- required for Raw HID support
       snippet: studio-rpc-usb-uart # <-- required for ZMK Studio support

   Note: If you are using a split keyboard, the change above is only required for the central half.

3. Enable ZMK Studio support in your .conf file:

   CONFIG_ZMK_STUDIO=y

   If your keyboard does not support ZMK Studio yet, adding support is described in the ZMK documentation.

KeyPeek will read layout and keymap directly from the device for ZMK without requiring additional configuration.

Note

If the keyboard has been paired via Bluetooth before enabling raw HID support, re-pairing may be necessary to allow the new communication channel.

Usage

Connecting

• Desktop: Devices are scanned when the app starts. For QMK you will be prompted to select the keyboard_info.json generated from your keymap when you connect. For Vial and ZMK, just select the connected device from the dropdown, since they provide layout information directly.
• Web: In a browser supporting WebHID, Web Serial, or Web Bluetooth (such as Chrome or Edge), select your keyboard using the browser pairing dialog.

Keymap Editor

While the settings window is open, clicking any key on the overlay opens the key editor. From there keycodes and behaviors can be selected from categorized lists or found using the search bar. You can switch between layers using the buttons at the top of the editor or click another key on the overlay to change the selection. Key changes are sent directly to the keyboard over the connection.

Support

If you're enjoying KeyPeek, I'd be truly grateful for your support! You can show your appreciation by giving a star on GitHub or making a donation:

• Buy me a coffee
• Donate via PayPal

License & Attribution

Parts of this project are based on code from the VIA project, which is licensed under the GNU General Public License v3.0.