zmk-buddy 0.1.2

A live keymap visualization tool for ZMK keyboards.

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:

Platform	Backend	Notes
Linux	evdev (preferred)	Requires user to be in input group
Windows	pynput	'should' work, but untested by me - let me know how it goes for you?
macOS	pynput	May require Accessibility permissions in System Preferences (also untested)

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, [e-mail] GPL V3 license