KeyPeek provides a live on-screen overlay with an integrated keymap editor for your keyboard. The overlay updates instantly to mirror active base and momentary layers, which is especially useful when learning complex layouts or using boards with missing legends. Keys can be remapped directly from the overlay, sending keycode and behavior updates to the device on the fly. KeyPeek currently supports QMK, Vial, and ZMK keyboards.

KeyPeek in action

KeyPeek requires a small firmware module because stock QMK/Vial/ZMK firmware does not expose live layer-change events. The module adds that event stream over the device connection, so the overlay stays in sync with your active layers in real time.

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.

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.

Key editor screenshot

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.

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.

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

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