ZMK Buddy

A live keymap visualization tool for ZMK keyboards, built on top of keymap-drawer.

Features

• Live visualization of keyboard key presses
• Overlay display with configurable transparency
• Support for ZMK keymap YAML files
• Global keyboard monitoring (requires appropriate permissions)
• Learning Mode: Tracks your typing accuracy to help you learn touch typing

Learning Mode

ZMK Buddy includes a learning feature to help you master touch typing without looking at the keyboard:

• Accuracy Tracking: Monitors each keypress and guesses at errors (i.e. it saw you press backspace after a key)
• Progress Persistence: Statistics are saved to your local data directory and persist between sessions
• Visual Feedback: Keys you've mastered are significantly dimmed, encouraging you to rely on muscle memory
• Progress Summary: Shows your overall learning progress at startup

How It Works

1. Each key starts with a score of 0%
2. Each time you type a key, it's tracked as "pending"
3. If you press another key (not backspace), the pending key is marked as correct (+1% to score)
4. If you press backspace, the pending key is marked as incorrect (-5% to score)
5. Once a key's score exceeds 80%, it's considered "learned" and dimmed in the display (to make it harder for you to 'cheat' by looking at the on-screen keyboard)
6. If accuracy falls below 80% the visible key reappears as a hint to help you find it

Installation

pipx install zmk-buddy

Usage

zmk-buddy --keymap keymap.yaml

You will want to use the keymap.yaml file generated by keymap-drawer. This is how we know where/how to draw keys and what the layer options are.

Some ZMK keyboard builds auto generate keymap.yaml automatically, otherwise see the keymap-drawer documentation for how to generate one for your keyboard/layout. You can either use their command line tool or their webapp to generate this yaml file.

If you do not specify a keymap a placeholder example keymap is used, which is probably not what you want.

Options

• -d, --debug: Enable debug logging
• -k, --keymap <file>: Load a custom keymap YAML file

Controls

• FIXME to cycle through layers
• FIXME to exit
• Drag the window to reposition it

Requirements

• Python 3.12+

Platform Support

ZMK Buddy supports global keyboard monitoring across all major platforms:

Linux Permissions

For global keyboard monitoring on Linux, your user needs access to /dev/input/event* devices. Add your user to the input group:

sudo usermod -aG input $USER

Then log out and back in for the change to take effect.

License

Copyright 2026 Kevin Hester, kevinh@geeksville.com GPL V3 license