KeyPeek (Crosses 42 fork)

Fork notice. This is a personal fork of srwi/keypeek with hardcoded keycap-label overrides for the Crosses 42 split keyboard's custom ZMK behaviors (HRMs, tap-dances, mod-morphs). See src/zmk_keycode_labels/crosses42.rs for the mapping table and a stability caveat. Build with cargo build --release.

Hotkey coach (fork feature)

On Windows, the fork can show a separate, click-through hotkey hint panel selected by the executable that owns the foreground window. The starter profile matches zed.exe and contains essential Herdr keyboard bindings for using Herdr inside Zed's terminal. This first MVP matches the application process, not the terminal contents. The bundled profile appears in Zed while either Ctrl is held or the connected ZMK keyboard reports its Nav layer active.

On first run KeyPeek creates the editable configuration at:

%APPDATA%\srwi\KeyPeek\config\hotkey-coach.json

The file is checked once per second, so valid edits appear without restarting KeyPeek. Invalid edits leave the last valid configuration active and show a notice. Set KEYPEEK_HOTKEY_COACH_CONFIG to an absolute path before launching KeyPeek when an agent or another tool should manage the live file somewhere else.

See docs/HOTKEY_COACH.md for the complete JSON contract, source map, current limitations, and extension guide. The bundled first-run template is resources/hotkey-coach.json.

---

The remaining sections are upstream documentation and apply unchanged.

KeyPeek provides a live on-screen overlay of your keyboard, mirroring the active base and momentary layers. It is especially useful when learning complex multi-layer layouts or using boards with missing legends. The overlay updates instantly when layers change, so the view always matches your firmware state. KeyPeek currently supports QMK, Vial, and ZMK keyboards.

Setup

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.

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

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.

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.